diff --git a/packages/mosaic/framework/install.sh b/packages/mosaic/framework/install.sh index 80cd20a..5083a41 100755 --- a/packages/mosaic/framework/install.sh +++ b/packages/mosaic/framework/install.sh @@ -21,11 +21,19 @@ INSTALL_MODE="${MOSAIC_INSTALL_MODE:-prompt}" # Files/dirs preserved across upgrades (never overwritten). # User-created content in these paths survives rsync --delete. -PRESERVE_PATHS=("AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials") +PRESERVE_PATHS=("CONSTITUTION.md" "AGENTS.md" "SOUL.md" "USER.md" "TOOLS.md" "STANDARDS.md" "memory" "sources" "credentials") + +# Framework-owned contract files: re-copied from defaults/ on every upgrade (the +# user must not edit them; a divergent copy is backed up once before overwrite). +# USER_SEEDED files are written once on first install, then owned by the user. +# Both lists are APPEND-FRIENDLY — add a new shipped framework file here and to the +# matching list in packages/mosaic/src/config/file-adapter.ts. +FRAMEWORK_OWNED=("CONSTITUTION.md" "AGENTS.md" "STANDARDS.md") +USER_SEEDED=("TOOLS.md") # Current framework schema version — bump this when the layout changes. # The migration system uses this to run upgrade steps. -FRAMEWORK_VERSION=2 +FRAMEWORK_VERSION=3 # ─── colours ────────────────────────────────────────────────────────────────── if [[ -t 1 ]]; then @@ -40,6 +48,45 @@ warn() { echo -e " ${YELLOW}⚠${RESET} $1" >&2; } fail() { echo -e " ${RED}✗${RESET} $1" >&2; } step() { echo -e "\n${BOLD}$1${RESET}"; } +# ─── snapshot / restore (crash safety for upgrades) ────────────────────────── +SNAPSHOT_DIR="" +make_snapshot() { + is_existing_install || return 0 + SNAPSHOT_DIR="$(mktemp -d "${TMPDIR:-/tmp}/mosaic-snapshot-XXXXXX")" + cp -a "$TARGET_DIR/." "$SNAPSHOT_DIR/" 2>/dev/null || true +} +restore_snapshot() { + [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] || return 0 + fail "Install interrupted/failed — restoring previous state from snapshot" + rm -rf "$TARGET_DIR"; mkdir -p "$TARGET_DIR" + cp -a "$SNAPSHOT_DIR/." "$TARGET_DIR/" 2>/dev/null || true +} +cleanup_snapshot() { [[ -n "$SNAPSHOT_DIR" && -d "$SNAPSHOT_DIR" ]] && rm -rf "$SNAPSHOT_DIR"; SNAPSHOT_DIR=""; } + +# Reconcile contract files after sync: framework-owned overwrite (backup-once), +# user-seeded seed-if-absent. +reconcile_framework_files() { + local defaults="$TARGET_DIR/defaults" f + [[ -d "$defaults" ]] || return 0 + for f in "${FRAMEWORK_OWNED[@]}"; do + [[ -f "$defaults/$f" ]] || continue + if [[ -f "$TARGET_DIR/$f" ]] && ! cmp -s "$TARGET_DIR/$f" "$defaults/$f"; then + if [[ ! -f "$TARGET_DIR/${f}.pre-constitution.bak" ]]; then + cp "$TARGET_DIR/$f" "$TARGET_DIR/${f}.pre-constitution.bak" + warn "$f is now framework-owned and was updated; your previous copy is saved as ${f}.pre-constitution.bak — re-apply intended changes as a .local overlay or policy/ file (see CONSTITUTION.md / constitution/LAYER-MODEL.md)." + fi + fi + cp "$defaults/$f" "$TARGET_DIR/$f" + done + for f in "${USER_SEEDED[@]}"; do + [[ -f "$defaults/$f" ]] || continue + if [[ ! -f "$TARGET_DIR/$f" ]]; then + cp "$defaults/$f" "$TARGET_DIR/$f" + ok "Seeded $f from defaults" + fi + done +} + # ─── helpers ────────────────────────────────────────────────────────────────── is_existing_install() { @@ -113,11 +160,14 @@ sync_framework() { fi if command -v rsync >/dev/null 2>&1; then - local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version") + local rsync_args=(-a --delete --exclude ".git" --exclude ".framework-version" --exclude "*.pre-constitution.bak") if [[ "$INSTALL_MODE" == "keep" ]]; then + # Anchor to the transfer root (leading /) so we preserve the TOP-LEVEL + # ~/.config/mosaic/ without also excluding defaults/ from sync + # (reconcile_framework_files needs the freshly-synced defaults/ copies). for path in "${PRESERVE_PATHS[@]}"; do - rsync_args+=(--exclude "$path") + rsync_args+=(--exclude "/$path") done fi @@ -137,7 +187,7 @@ sync_framework() { done fi - find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" -exec rm -rf {} + + find "$TARGET_DIR" -mindepth 1 -maxdepth 1 ! -name ".git" ! -name ".framework-version" ! -name "*.pre-constitution.bak" -exec rm -rf {} + cp -R "$SOURCE_DIR"/. "$TARGET_DIR"/ rm -rf "$TARGET_DIR/.git" @@ -195,10 +245,15 @@ run_migrations() { fi fi - # ── Future migrations go here ────────────────────────────────────────────── - # if [[ "$from_version" -lt 3 ]]; then - # ... - # fi + # ── Migration: v2 → v3 (Constitution split) ─────────────────────────────── + # CONSTITUTION.md / AGENTS.md / STANDARDS.md become framework-owned (overwritten + # on upgrade). reconcile_framework_files() has already run before this point: it + # backed up any user-edited copy to .pre-constitution.bak and installed the + # new framework version. Nothing further to do here — the advisory was emitted at + # reconcile time. (STANDARDS.local.md composition lands with the overlay composer.) + if [[ "$from_version" -lt 3 ]]; then + ok "Migrated to the Constitution layout (framework-owned CONSTITUTION/AGENTS/STANDARDS)" + fi } # ═══════════════════════════════════════════════════════════════════════════════ @@ -216,6 +271,10 @@ else ok "Install mode: overwrite" fi +# Snapshot before any destructive file operation; restore on interrupt/failure. +make_snapshot +trap 'restore_snapshot' ERR INT TERM + sync_framework # Ensure persistent directories exist @@ -230,15 +289,7 @@ mkdir -p "$TARGET_DIR/credentials" # packages/mosaic/src/config/file-adapter.ts (FileConfigAdapter.syncFramework). # SOUL.md and USER.md are intentionally NOT seeded here — they are generated # by `mosaic init` from templates with user-supplied values. -DEFAULTS_DIR="$TARGET_DIR/defaults" -if [[ -d "$DEFAULTS_DIR" ]]; then - for default_file in CONSTITUTION.md AGENTS.md STANDARDS.md TOOLS.md; do - if [[ -f "$DEFAULTS_DIR/$default_file" ]] && [[ ! -f "$TARGET_DIR/$default_file" ]]; then - cp "$DEFAULTS_DIR/$default_file" "$TARGET_DIR/$default_file" - ok "Seeded $default_file from defaults" - fi - done -fi +reconcile_framework_files # Ensure tool scripts are executable find "$TARGET_DIR/tools" -name "*.sh" -exec chmod +x {} + 2>/dev/null || true @@ -249,6 +300,18 @@ ok "Framework synced to $TARGET_DIR" # Run migrations before post-install (migrations may remove old bin/ etc.) run_migrations +# File-system phase complete and consistent — clear the restore trap. +trap - ERR INT TERM +cleanup_snapshot + +# Testability / minimal-install hook: stop after the file-system phase, before any +# environment-touching post-install steps (runtime linking, MCP setup, skills, doctor). +if [[ "${MOSAIC_SYNC_ONLY:-0}" == "1" ]]; then + write_framework_version + ok "Sync-only mode: file phase complete" + exit 0 +fi + step "Post-install tasks" SCRIPTS="$TARGET_DIR/tools/_scripts" diff --git a/packages/mosaic/framework/tools/_scripts/mosaic-init b/packages/mosaic/framework/tools/_scripts/mosaic-init index 57704c9..08830f9 100755 --- a/packages/mosaic/framework/tools/_scripts/mosaic-init +++ b/packages/mosaic/framework/tools/_scripts/mosaic-init @@ -274,6 +274,13 @@ detect_existing_config echo "[mosaic-init] Generating SOUL.md — agent identity contract" echo "" +# Fail-closed persona: in non-interactive mode the agent NAME must be supplied +# explicitly (--name) — never silently ship an agent named "Assistant". +if [[ $NON_INTERACTIVE -eq 1 && -z "$AGENT_NAME" ]]; then + echo "[mosaic-init] ERROR: --name (agent name) is required in non-interactive mode." >&2 + exit 1 +fi + prompt_if_empty AGENT_NAME "What name should agents use" "Assistant" prompt_if_empty ROLE_DESCRIPTION "Agent role description" "execution partner and visibility engine" diff --git a/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh b/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh new file mode 100755 index 0000000..9b8647a --- /dev/null +++ b/packages/mosaic/framework/tools/quality/scripts/test-install-migration.sh @@ -0,0 +1,67 @@ +#!/usr/bin/env bash +# test-install-migration.sh — fixture matrix for the v2→v3 (Constitution) upgrade +# migration in install.sh. Runs the installer against throwaway MOSAIC_HOME dirs +# with MOSAIC_SYNC_ONLY=1 (file phase only — no environment-touching post-install) +# and asserts the framework-owned-overwrite + user-preserve + backup semantics. +# +# Mirrors the TS fixture suite in packages/mosaic/src/config/file-adapter.test.ts; +# both installers MUST behave identically. +# +# Usage: bash test-install-migration.sh +set -uo pipefail + +FW="$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)" # packages/mosaic/framework +INSTALL="$FW/install.sh" +DEFA="$FW/defaults" + +pass=0; fail=0 +chk() { if eval "$2"; then echo " ✓ $1"; pass=$((pass + 1)); else echo " ✗ $1"; fail=$((fail + 1)); fi; } +run() { MOSAIC_HOME="$1" MOSAIC_INSTALL_MODE="$2" MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >/dev/null 2>&1; } + +echo "install.sh v2→v3 migration fixture matrix:" + +# F1 — fresh install +T1=$(mktemp -d); run "$T1" overwrite +chk "F1 fresh: CONSTITUTION/AGENTS/STANDARDS/TOOLS seeded" \ + "[ -f '$T1/CONSTITUTION.md' ] && [ -f '$T1/AGENTS.md' ] && [ -f '$T1/STANDARDS.md' ] && [ -f '$T1/TOOLS.md' ]" +chk "F1 fresh: AGENTS == shipped default" "cmp -s '$T1/AGENTS.md' '$DEFA/AGENTS.md'" +chk "F1 fresh: framework-version stamped 3" "[ \"\$(cat '$T1/.framework-version' 2>/dev/null)\" = 3 ]" + +# F2 — legacy install with a user-edited AGENTS.md (the sanctioned pre-constitution customization) +T2=$(mktemp -d); mkdir -p "$T2/credentials" +printf '# user-edited AGENTS pre-constitution\n' > "$T2/AGENTS.md" +printf '# my persona\n' > "$T2/SOUL.md" +printf 'token\n' > "$T2/credentials/c.json" +echo 2 > "$T2/.framework-version" +run "$T2" keep +chk "F2 legacy-edited: AGENTS overwritten to framework version" "cmp -s '$T2/AGENTS.md' '$DEFA/AGENTS.md'" +chk "F2 legacy-edited: prior AGENTS saved to .pre-constitution.bak" \ + "grep -q 'user-edited AGENTS pre-constitution' '$T2/AGENTS.md.pre-constitution.bak'" +chk "F2 legacy-edited: SOUL.md preserved" "grep -q 'my persona' '$T2/SOUL.md'" +chk "F2 legacy-edited: credentials preserved" "grep -q token '$T2/credentials/c.json'" +chk "F2 legacy-edited: CONSTITUTION.md installed" "[ -f '$T2/CONSTITUTION.md' ]" +run "$T2" keep +chk "F2 idempotent: .pre-constitution.bak preserved across a 2nd upgrade" \ + "grep -q 'user-edited AGENTS pre-constitution' '$T2/AGENTS.md.pre-constitution.bak'" + +# F3 — user-tuned STANDARDS.md +T3=$(mktemp -d); printf '# tuned standards\n' > "$T3/STANDARDS.md"; printf '# persona\n' > "$T3/SOUL.md"; echo 2 > "$T3/.framework-version" +run "$T3" keep +chk "F3 tuned-standard: STANDARDS overwritten" "cmp -s '$T3/STANDARDS.md' '$DEFA/STANDARDS.md'" +chk "F3 tuned-standard: tuned copy backed up" "grep -q 'tuned standards' '$T3/STANDARDS.md.pre-constitution.bak'" + +# F4 — unattended / no TTY (stdin closed): must complete without hanging, default to keep +T4=$(mktemp -d); printf '# persona\n' > "$T4/SOUL.md"; printf '# old\n' > "$T4/AGENTS.md"; echo 2 > "$T4/.framework-version" +MOSAIC_HOME="$T4" MOSAIC_SYNC_ONLY=1 bash "$INSTALL" /dev/null 2>&1 +chk "F4 no-TTY: completed, AGENTS updated" "cmp -s '$T4/AGENTS.md' '$DEFA/AGENTS.md'" + +# F5 — failure path must not corrupt existing data (invalid mode rejected before any file op) +T5=$(mktemp -d); mkdir -p "$T5/credentials"; printf '# orig\n' > "$T5/SOUL.md"; printf 'keepme\n' > "$T5/credentials/c.json"; echo 2 > "$T5/.framework-version" +MOSAIC_HOME="$T5" MOSAIC_INSTALL_MODE=bogus MOSAIC_SYNC_ONLY=1 bash "$INSTALL" >/dev/null 2>&1; rc=$? +chk "F5 failure: invalid mode rejected (nonzero exit)" "[ $rc -ne 0 ]" +chk "F5 failure: SOUL + credentials intact" "grep -q orig '$T5/SOUL.md' && grep -q keepme '$T5/credentials/c.json'" + +rm -rf "$T1" "$T2" "$T3" "$T4" "$T5" +echo +echo "RESULT: $pass passed, $fail failed" +[ "$fail" -eq 0 ] diff --git a/packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh b/packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh index 4324f8e..9de53c7 100755 --- a/packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh +++ b/packages/mosaic/framework/tools/quality/scripts/verify-sanitized.sh @@ -53,9 +53,15 @@ _selftest() { local tmp; tmp="$(mktemp -d)" || return 1 printf 'contact jason.woltje at jarvis-brain (PDA-friendly)\n' > "$tmp/planted.md" printf 'X="${VAR:-$HOME/src/whatever/x.json}"\n' > "$tmp/planted.sh" + printf 'name: jason-woltje\n' > "$tmp/planted.yaml" + printf '[Service]\nUser=jarvis\n' > "$tmp/planted.service" local rc=0 grep -qIEi "$DENYLIST" "$tmp/planted.md" || { echo "✗ SELF-TEST: identity denylist regex broken" >&2; rc=1; } grep -qIE "$STRUCTURAL_SH" "$tmp/planted.sh" || { echo "✗ SELF-TEST: structural regex broken" >&2; rc=1; } + # Prove the identity scan covers the config formats it claims to (yaml/service/etc). + local n_ext + n_ext=$(find "$tmp" -type f \( -name '*.yaml' -o -name '*.service' \) -print0 | xargs -0 -r grep -lIEi "$DENYLIST" 2>/dev/null | wc -l) + [[ "$n_ext" -eq 2 ]] || { echo "✗ SELF-TEST: identity scan does not cover .yaml/.service extensions" >&2; rc=1; } rm -rf "$tmp"; return $rc } _selftest || exit 2 diff --git a/packages/mosaic/src/config/file-adapter.test.ts b/packages/mosaic/src/config/file-adapter.test.ts index 48f411a..b8629d7 100644 --- a/packages/mosaic/src/config/file-adapter.test.ts +++ b/packages/mosaic/src/config/file-adapter.test.ts @@ -99,11 +99,8 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => { ); }); - it('preserves existing contract files — never overwrites user customization', async () => { - // Also plant a root-level AGENTS.md in sourceDir so that `syncDirectory` - // itself (not just the seed loop) has something to try to overwrite. - // Without this, the test would silently pass even if preserve semantics - // were broken in syncDirectory. + it('overwrites framework-owned files (backup-once) but preserves user-seeded files', async () => { + // Plant a root-level AGENTS.md in sourceDir so syncDirectory's preserve is exercised. writeFileSync(join(fixture.sourceDir, 'AGENTS.md'), '# shipped AGENTS from source root\n'); writeFileSync(join(fixture.mosaicHome, 'TOOLS.md'), '# user-customized TOOLS\n'); @@ -112,18 +109,50 @@ describe('FileConfigAdapter.syncFramework — defaults seeding', () => { const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir); await adapter.syncFramework('keep'); + // User-seeded TOOLS.md is preserved. expect(readFileSync(join(fixture.mosaicHome, 'TOOLS.md'), 'utf-8')).toBe( '# user-customized TOOLS\n', ); - expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe( + // Framework-owned AGENTS.md is overwritten from defaults/ ... + expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n'); + // ... and the user's prior copy is backed up exactly once. + expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md.pre-constitution.bak'), 'utf-8')).toBe( '# user-customized AGENTS\n', ); - // And the missing contract file still gets seeded. + // Framework-owned STANDARDS.md (absent) gets installed. expect(readFileSync(join(fixture.mosaicHome, 'STANDARDS.md'), 'utf-8')).toContain( '# STANDARDS default', ); }); + it('backs up a divergent framework-owned file only once (idempotent across re-sync)', async () => { + writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n'); + const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir); + + await adapter.syncFramework('keep'); // 1st: backup created, AGENTS overwritten + await adapter.syncFramework('keep'); // 2nd: AGENTS already == default, no new backup + + expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md.pre-constitution.bak'), 'utf-8')).toBe( + '# user-customized AGENTS\n', + ); + }); + + it('preserves SOUL.md and credentials through a framework-owned overwrite', async () => { + writeFileSync(join(fixture.mosaicHome, 'SOUL.md'), '# my persona\n'); + writeFileSync(join(fixture.mosaicHome, 'AGENTS.md'), '# user-customized AGENTS\n'); + mkdirSync(join(fixture.mosaicHome, 'credentials'), { recursive: true }); + writeFileSync(join(fixture.mosaicHome, 'credentials', 'c.json'), 'token\n'); + + const adapter = new FileConfigAdapter(fixture.mosaicHome, fixture.sourceDir); + await adapter.syncFramework('keep'); + + expect(readFileSync(join(fixture.mosaicHome, 'SOUL.md'), 'utf-8')).toBe('# my persona\n'); + expect(readFileSync(join(fixture.mosaicHome, 'credentials', 'c.json'), 'utf-8')).toBe( + 'token\n', + ); + expect(readFileSync(join(fixture.mosaicHome, 'AGENTS.md'), 'utf-8')).toBe('# AGENTS default\n'); + }); + it('is a no-op for seeding when defaults/ dir does not exist', async () => { rmSync(fixture.defaultsDir, { recursive: true }); diff --git a/packages/mosaic/src/config/file-adapter.ts b/packages/mosaic/src/config/file-adapter.ts index 3b6cd9c..ea92f6d 100644 --- a/packages/mosaic/src/config/file-adapter.ts +++ b/packages/mosaic/src/config/file-adapter.ts @@ -13,12 +13,17 @@ import { join } from 'node:path'; * This list must match the explicit seed loop in * packages/mosaic/framework/install.sh. */ -export const DEFAULT_SEED_FILES = [ - 'CONSTITUTION.md', - 'AGENTS.md', - 'STANDARDS.md', - 'TOOLS.md', -] as const; +// Framework-owned contract files: re-copied from defaults/ on every upgrade (a +// divergent existing copy is backed up once to .pre-constitution.bak first). +// MUST match FRAMEWORK_OWNED in packages/mosaic/framework/install.sh (append-friendly). +export const FRAMEWORK_OWNED_FILES = ['CONSTITUTION.md', 'AGENTS.md', 'STANDARDS.md'] as const; + +// User-seeded contract files: written once on first install, then owned by the user. +// MUST match USER_SEEDED in packages/mosaic/framework/install.sh. +export const USER_SEEDED_FILES = ['TOOLS.md'] as const; + +// Union, retained for callers/tests that assert the full seed set on a fresh install. +export const DEFAULT_SEED_FILES = [...FRAMEWORK_OWNED_FILES, ...USER_SEEDED_FILES] as const; import type { ConfigService, ConfigSection, ResolvedConfig } from './config-service.js'; import type { SoulConfig, UserConfig, ToolsConfig, InstallAction } from '../types.js'; import { soulSchema, userSchema, toolsSchema } from './schemas.js'; @@ -159,6 +164,7 @@ export class FileConfigAdapter implements ConfigService { const preservePaths = action === 'keep' || action === 'reconfigure' ? [ + 'CONSTITUTION.md', 'AGENTS.md', 'SOUL.md', 'USER.md', @@ -175,10 +181,10 @@ export class FileConfigAdapter implements ConfigService { excludeGit: true, }); - // Copy framework-contract files (AGENTS.md, STANDARDS.md, TOOLS.md) - // from framework/defaults/ into the mosaic home root if they don't - // exist yet. These are written on first install only and are never - // overwritten afterwards — the user may have customized them. + // Reconcile framework-contract files from framework/defaults/ into the mosaic + // home root: framework-owned files (CONSTITUTION/AGENTS/STANDARDS) are overwritten + // every upgrade (backup-once); user-seeded files (TOOLS) are written on first + // install only. Mirrors reconcile_framework_files() in install.sh. // // SOUL.md and USER.md are deliberately NOT seeded here. They are // generated from templates by the soul/user wizard stages with @@ -186,7 +192,20 @@ export class FileConfigAdapter implements ConfigService { // identity flow and leak placeholder content into the mosaic home. const defaultsDir = join(this.sourceDir, 'defaults'); if (existsSync(defaultsDir)) { - for (const entry of DEFAULT_SEED_FILES) { + // Framework-owned: overwrite from defaults/ every sync; back up a divergent + // existing copy ONCE to .pre-constitution.bak before the first overwrite. + for (const entry of FRAMEWORK_OWNED_FILES) { + const src = join(defaultsDir, entry); + const dest = join(this.mosaicHome, entry); + if (!existsSync(src) || !statSync(src).isFile()) continue; + const bak = `${dest}.pre-constitution.bak`; + if (existsSync(dest) && !readFileSync(src).equals(readFileSync(dest)) && !existsSync(bak)) { + copyFileSync(dest, bak); + } + copyFileSync(src, dest); + } + // User-seeded: write only if absent. + for (const entry of USER_SEEDED_FILES) { const src = join(defaultsDir, entry); const dest = join(this.mosaicHome, entry); if (existsSync(dest)) continue;