argos-harness 0.1.0 → 0.2.1

package/dist/commands/init.js

@@ -6,9 +6,10 @@ import { listAgentIds, listSkillFiles, listSkillIds, MANAGED_BLOCK_IDS, readAsse
 import { writeFileAtomic } from "../lib/atomic-write.js";
 import { createBackup } from "../lib/backup.js";
 import { injectBlock, listBlocks } from "../lib/markers.js";
-import { hasArgosFileMarker, writeManagedFile, writeManagedShellFile } from "../lib/managed-files.js";
+import { hasArgosFileMarker, hasArgosShellFileMarker, writeManagedFile, writeManagedShellFile } from "../lib/managed-files.js";
 import { resolveArgosHome, resolveClaudeDir } from "../lib/paths.js";
-import { mergeHooksIntoSettings } from "../lib/settings-merge.js";
+import { applyOutputStylePolicy, isNavoriOutputStyle, mergeHooksIntoSettings } from "../lib/settings-merge.js";
+import { isInteractive, clackPrompter } from "../lib/prompter.js";
 import { readCliVersion } from "../lib/version.js";
 /**
  * Ids (basenames under assets/hooks/) of the 2 global hooks argos init
@@ -32,6 +33,7 @@ const STATUS_COUNT_ORDER = [
     "updated",
     "unchanged",
     "skipped-foreign",
+    "overwritten-foreign",
     "error"
 ];
 function summarize(rows) {
@@ -40,6 +42,7 @@ function summarize(rows) {
         updated: 0,
         unchanged: 0,
         "skipped-foreign": 0,
+        "overwritten-foreign": 0,
         error: 0
     };
     for (const row of rows)counts[row.status]++;
@@ -70,6 +73,23 @@ function errorMessage(err) {
     writeFileAtomic(destPath, sourceContent);
     return "updated";
 }
+/**
+ * `--force` counterpart to `writePlainFile`, used only for a supporting file
+ * (e.g. `references/core.md`) that lives under a skill directory whose
+ * `SKILL.md` was just detected as foreign (no `argos:file` marker). These
+ * plain subfiles never carry a marker of their own — the whole skill
+ * directory's ownership is decided once from `SKILL.md` (see the skills loop
+ * below) — so this always overwrites unconditionally: `overwritten-foreign`
+ * when something was already there to replace, `created` when the motor
+ * ships a subfile the foreign directory never had.
+ */ function writeForcedPlainFile(destPath, sourceContent) {
+    const existed = existsSync(destPath);
+    if (!existed) mkdirSync(dirname(destPath), {
+        recursive: true
+    });
+    writeFileAtomic(destPath, sourceContent);
+    return existed ? "overwritten-foreign" : "created";
+}
 /** Inject one managed CLAUDE.md block, reporting created/updated/unchanged. */ function injectAndReport(claudeMd, id, version, content) {
     const hadBlock = listBlocks(claudeMd).some((b)=>b.id === id);
     const after = injectBlock(claudeMd, id, version, content);
@@ -86,6 +106,9 @@ function errorMessage(err) {
  * filesystem — no process.exit, no console output.
  */ export function runInit(options = {}) {
     const language = options.language ?? "es";
+    const installAgents = options.installAgents ?? true;
+    const installHooks = options.installHooks ?? true;
+    const force = options.force ?? false;
     const version = readCliVersion();
     const claudeDir = resolveClaudeDir();
     const assetsDir = resolveAssetsDir();
@@ -117,7 +140,7 @@ function errorMessage(err) {
             exitCode: 1
         };
     }
-    // 1. CLAUDE.md — 5 managed blocks, in order.
+    // 1. CLAUDE.md — MANAGED_BLOCK_IDS.length managed blocks, in order.
     const claudeMdPath = join(claudeDir, "CLAUDE.md");
     let claudeMd = existsSync(claudeMdPath) ? readFileSync(claudeMdPath, "utf-8") : "";
     const blockResults = [];
@@ -147,22 +170,27 @@ function errorMessage(err) {
             detail
         });
     }
-    // 2. Full-file assets: output-style, agents.
+    // 2. Full-file assets: output-style always, agents gated by the
+    // `installAgents` toggle (default true; the wizard's "agentes sí/no"
+    // step — spec 0004). Skills below are NEVER gated: they load on-demand
+    // and trimming the set breaks the arsenal.
     const fullFiles = [
         [
             "output-styles",
             "argos.md"
         ],
-        ...listAgentIds(assetsDir).map((id)=>[
+        ...installAgents ? listAgentIds(assetsDir).map((id)=>[
                 "agents",
                 `${id}.md`
-            ])
+            ]) : []
     ];
     for (const relPath of fullFiles){
         const source = readAsset(assetsDir, ...relPath);
         const dest = join(claudeDir, ...relPath);
         try {
-            const status = writeManagedFile(dest, source, version);
+            const status = writeManagedFile(dest, source, version, {
+                force
+            });
             rows.push({
                 path: join(...relPath),
                 status
@@ -182,14 +210,18 @@ function errorMessage(err) {
     //   file the skill ships.
     // - SKILL.md present WITHOUT the marker (foreign/user-modified) → skip
     //   every file under that skill dir, untouched — same policy as a single
-    //   foreign full-file asset above, extended to the whole directory.
+    //   foreign full-file asset above, extended to the whole directory. Under
+    //   `--force`, every file in that directory is overwritten instead
+    //   (`overwritten-foreign`) — SKILL.md gets its marker stamped via
+    //   `writeManagedFile`'s own `force` path, and each plain subfile is
+    //   force-written via `writeForcedPlainFile` (see its own doc comment).
     for (const skillId of listSkillIds(assetsDir)){
         const skillMdDest = join(claudeDir, "skills", skillId, "SKILL.md");
         const isForeignSkill = existsSync(skillMdDest) && !hasArgosFileMarker(readFileSync(skillMdDest, "utf-8"));
         for (const relFile of listSkillFiles(assetsDir, skillId)){
             const relParts = relFile.split("/");
             const relPath = join("skills", skillId, ...relParts);
-            if (isForeignSkill) {
+            if (isForeignSkill && !force) {
                 rows.push({
                     path: relPath,
                     status: "skipped-foreign"
@@ -199,7 +231,9 @@ function errorMessage(err) {
             const source = readAsset(assetsDir, "skills", skillId, ...relParts);
             const dest = join(claudeDir, "skills", skillId, ...relParts);
             try {
-                const status = relFile === "SKILL.md" ? writeManagedFile(dest, source, version) : writePlainFile(dest, source);
+                const status = relFile === "SKILL.md" ? writeManagedFile(dest, source, version, {
+                    force
+                }) : isForeignSkill ? writeForcedPlainFile(dest, source) : writePlainFile(dest, source);
                 rows.push({
                     path: relPath,
                     status
@@ -219,62 +253,92 @@ function errorMessage(err) {
     // write threw must NEVER get a settings.json entry (see 2c below): a
     // dangling PreToolUse entry pointing at a script that isn't there hard-
     // blocks every subsequent Bash call.
+    //
+    // Gated by the `installHooks` toggle (default true; the wizard's "hooks
+    // sí/no" step — spec 0004): when disabled, this run neither writes nor
+    // touches any pre-existing hook script/settings.json entry — a full
+    // uninstall of previously-installed hooks is `argos remove`'s job, not a
+    // side effect of toggling this flag off on a later `init` run.
     const hookWriteFailed = new Map();
-    for (const id of HOOK_IDS){
-        const relPath = [
-            "hooks",
-            `${id}.sh`
-        ];
-        const source = readAsset(assetsDir, ...relPath);
-        const dest = join(claudeDir, ...relPath);
-        try {
-            const status = writeManagedShellFile(dest, source, version);
-            rows.push({
-                path: join(...relPath),
-                status
-            });
-            hookWriteFailed.set(id, false);
-        } catch (err) {
-            rows.push({
-                path: join(...relPath),
-                status: "error",
-                detail: errorMessage(err)
-            });
-            hookWriteFailed.set(id, true);
+    if (installHooks) {
+        for (const id of HOOK_IDS){
+            const relPath = [
+                "hooks",
+                `${id}.sh`
+            ];
+            const source = readAsset(assetsDir, ...relPath);
+            const dest = join(claudeDir, ...relPath);
+            try {
+                const status = writeManagedShellFile(dest, source, version, {
+                    force
+                });
+                rows.push({
+                    path: join(...relPath),
+                    status
+                });
+                hookWriteFailed.set(id, false);
+            } catch (err) {
+                rows.push({
+                    path: join(...relPath),
+                    status: "error",
+                    detail: errorMessage(err)
+                });
+                hookWriteFailed.set(id, true);
+            }
         }
+        // 2c. settings.json — surgical merge of the 2 PreToolUse hook entries.
+        // Only writes/updates entries whose command targets one of the 2 scripts
+        // above; every other key and hook in the user's settings.json is left
+        // untouched (see lib/settings-merge.ts). Only hooks whose script write
+        // actually succeeded get an entry built for them at all.
+        const settingsPath = join(claudeDir, "settings.json");
+        const allHookSpecs = {
+            "argos-guard-destructive": {
+                scriptPath: join(claudeDir, "hooks", "argos-guard-destructive.sh"),
+                matcher: "Bash",
+                timeout: 10,
+                statusMessage: "argos: guard-destructive"
+            },
+            "argos-quality-gate": {
+                scriptPath: join(claudeDir, "hooks", "argos-quality-gate.sh"),
+                matcher: "Bash",
+                timeout: QUALITY_GATE_OUTER_TIMEOUT_SECONDS,
+                statusMessage: "argos: quality-gate"
+            }
+        };
+        const hookSpecs = HOOK_IDS.filter((id)=>!hookWriteFailed.get(id)).map((id)=>allHookSpecs[id]);
+        // Any hook whose write just failed also gets its (possibly pre-existing,
+        // from an earlier successful run) settings.json entry stripped out — a
+        // script that's gone or broken must never be left with a live entry.
+        const failedScriptPaths = HOOK_IDS.filter((id)=>hookWriteFailed.get(id)).map((id)=>allHookSpecs[id].scriptPath);
+        const mergeResult = mergeHooksIntoSettings(settingsPath, hookSpecs, {
+            removeScriptPaths: failedScriptPaths
+        });
+        rows.push({
+            path: "settings.json",
+            status: mergeResult.status,
+            detail: mergeResult.detail
+        });
     }
-    // 2c. settings.json — surgical merge of the 2 PreToolUse hook entries.
-    // Only writes/updates entries whose command targets one of the 2 scripts
-    // above; every other key and hook in the user's settings.json is left
-    // untouched (see lib/settings-merge.ts). Only hooks whose script write
-    // actually succeeded get an entry built for them at all.
-    const settingsPath = join(claudeDir, "settings.json");
-    const allHookSpecs = {
-        "argos-guard-destructive": {
-            scriptPath: join(claudeDir, "hooks", "argos-guard-destructive.sh"),
-            matcher: "Bash",
-            timeout: 10,
-            statusMessage: "argos: guard-destructive"
-        },
-        "argos-quality-gate": {
-            scriptPath: join(claudeDir, "hooks", "argos-quality-gate.sh"),
-            matcher: "Bash",
-            timeout: QUALITY_GATE_OUTER_TIMEOUT_SECONDS,
-            statusMessage: "argos: quality-gate"
-        }
-    };
-    const hookSpecs = HOOK_IDS.filter((id)=>!hookWriteFailed.get(id)).map((id)=>allHookSpecs[id]);
-    // Any hook whose write just failed also gets its (possibly pre-existing,
-    // from an earlier successful run) settings.json entry stripped out — a
-    // script that's gone or broken must never be left with a live entry.
-    const failedScriptPaths = HOOK_IDS.filter((id)=>hookWriteFailed.get(id)).map((id)=>allHookSpecs[id].scriptPath);
-    const mergeResult = mergeHooksIntoSettings(settingsPath, hookSpecs, {
-        removeScriptPaths: failedScriptPaths
+    // 2d. Voice activation (spec 0004 "Activación de la voz"):
+    // settings.json.outputStyle. Absent → set to "Argos". Matching the
+    // predecessor harness's voice (navori) → takeover per
+    // `takeoverNavoriVoice` (default true, i.e. unconditional replace under
+    // --yes/no-TTY; the interactive wizard passes `false` when the user
+    // declines). Any other value → never touched. Reported separately from
+    // the hooks settings.json row above so a takeover/foreign-voice detail is
+    // never conflated with the hooks merge outcome.
+    const outputStyleResult = applyOutputStylePolicy(join(claudeDir, "settings.json"), {
+        takeoverNavori: options.takeoverNavoriVoice ?? true
     });
+    // "untouched" (a foreign non-navori voice, or a declined navori takeover)
+    // maps to the same "skipped-foreign" row status used elsewhere for
+    // "found something not ours, left it byte-identical".
+    const outputStyleRowStatus = outputStyleResult.status === "untouched" ? "skipped-foreign" : outputStyleResult.status;
     rows.push({
-        path: "settings.json",
-        status: mergeResult.status,
-        detail: mergeResult.detail
+        path: "settings.json#outputStyle",
+        status: outputStyleRowStatus,
+        detail: outputStyleResult.detail
     });
     // 3. ~/.argos/global.json
     const argosHome = resolveArgosHome();
@@ -309,6 +373,194 @@ function errorMessage(err) {
         backupPath
     };
 }
+/**
+ * A cancelled wizard's report: identical shape to a run that touched
+ * nothing. `exitCode: 1` — a cancel is neither a successful write nor
+ * silently indistinguishable from one by exit code alone (matches
+ * `runWorkspaceLinkInteractive`'s convention for its own cancel paths).
+ */ function cancelledInitReport() {
+    return {
+        rows: [],
+        summary: "argos init: cancelado — no se tocó nada.",
+        exitCode: 1
+    };
+}
+/**
+ * Read-only peek at `settings.json.outputStyle`, used only to decide whether
+ * the interactive wizard needs to ask about a navori takeover. Never throws,
+ * never writes — any missing file, unreadable file, or invalid JSON just
+ * reads as "no value" (`undefined`), which is safely a non-match for
+ * `isNavoriOutputStyle`. The actual write happens inside `runInit` via
+ * `applyOutputStylePolicy`, which re-does this read itself under its own
+ * mtime-guarded contract.
+ */ function peekOutputStyleValue(settingsPath) {
+    if (!existsSync(settingsPath)) return undefined;
+    try {
+        const parsed = JSON.parse(readFileSync(settingsPath, "utf-8"));
+        if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) return undefined;
+        return parsed.outputStyle;
+    } catch  {
+        return undefined;
+    }
+}
+/**
+ * Read-only `--force` pre-flight: counts how many on-disk paths at motor
+ * paths (output-style, agents, skills incl. every manifest subfile, hooks)
+ * are foreign (no `argos:file`/shell marker) and would therefore be
+ * overwritten by a forced `runInit`. Used only by the interactive wizard to
+ * size its confirm prompt — the actual overwrite decision and write happen
+ * inside `runInit` itself, independently, so this can never drift into
+ * writing anything. Mirrors the same directory-ownership rule `runInit`'s
+ * own skills loop uses (SKILL.md's marker decides the whole directory), and
+ * — like `doctor.ts`'s own read-only checks — intentionally duplicates that
+ * iteration shape rather than sharing private state with the writer.
+ */ function countForceOverwrites(claudeDir, assetsDir, installAgents, installHooks) {
+    let count = 0;
+    const fullFiles = [
+        [
+            "output-styles",
+            "argos.md"
+        ],
+        ...installAgents ? listAgentIds(assetsDir).map((id)=>[
+                "agents",
+                `${id}.md`
+            ]) : []
+    ];
+    for (const relPath of fullFiles){
+        const dest = join(claudeDir, ...relPath);
+        if (existsSync(dest) && !hasArgosFileMarker(readFileSync(dest, "utf-8"))) count++;
+    }
+    for (const skillId of listSkillIds(assetsDir)){
+        const skillMdDest = join(claudeDir, "skills", skillId, "SKILL.md");
+        const isForeignSkill = existsSync(skillMdDest) && !hasArgosFileMarker(readFileSync(skillMdDest, "utf-8"));
+        if (!isForeignSkill) continue;
+        for (const relFile of listSkillFiles(assetsDir, skillId)){
+            const dest = join(claudeDir, "skills", skillId, ...relFile.split("/"));
+            if (existsSync(dest)) count++;
+        }
+    }
+    if (installHooks) {
+        for (const id of HOOK_IDS){
+            const dest = join(claudeDir, "hooks", `${id}.sh`);
+            if (existsSync(dest) && !hasArgosShellFileMarker(readFileSync(dest, "utf-8"))) count++;
+        }
+    }
+    return count;
+}
+/**
+ * Interactive layer over `runInit` (spec 0004 F5 "argos init"). A pure
+ * additive wrapper — the core `runInit` never changes behavior or contract.
+ * Without a real TTY, or with `--yes`, this delegates to `runInit(options)`
+ * unchanged: no prompt library call is ever reached on that path. With a
+ * TTY, it runs a 3-step wizard (language, agents/hooks toggles, summary +
+ * final confirm) before calling `runInit` with the gathered choices;
+ * cancelling at any step touches nothing and returns a no-op report.
+ */ export async function runInitInteractive(options = {}) {
+    if (!isInteractive({
+        yes: options.yes
+    })) {
+        return runInit(options);
+    }
+    const prompter = options.prompter ?? clackPrompter;
+    prompter.intro("argos init — instalación interactiva del motor");
+    const language = await prompter.select({
+        message: "Idioma del motor",
+        options: [
+            {
+                value: "es",
+                label: "es — español"
+            },
+            {
+                value: "en",
+                label: "en — English"
+            }
+        ],
+        initialValue: options.language ?? "es"
+    });
+    if (prompter.isCancel(language)) {
+        prompter.cancel("argos init cancelado — no se tocó nada.");
+        return cancelledInitReport();
+    }
+    const installAgents = await prompter.confirm({
+        message: "¿Instalar los agentes del motor (agents/)?",
+        initialValue: options.installAgents ?? true
+    });
+    if (prompter.isCancel(installAgents)) {
+        prompter.cancel("argos init cancelado — no se tocó nada.");
+        return cancelledInitReport();
+    }
+    const installHooks = await prompter.confirm({
+        message: "¿Instalar los hooks globales (guard-destructive + quality-gate)?",
+        initialValue: options.installHooks ?? true
+    });
+    if (prompter.isCancel(installHooks)) {
+        prompter.cancel("argos init cancelado — no se tocó nada.");
+        return cancelledInitReport();
+    }
+    const claudeDir = resolveClaudeDir();
+    // `--force` pre-flight (see `InitOptions.force`'s doc comment): flag-driven,
+    // not itself a wizard question. When active, count how many on-disk paths
+    // are foreign and about to be overwritten (read-only — see
+    // `countForceOverwrites`) and, only if that count is > 0, require an
+    // explicit confirm before proceeding. Zero foreign paths means force has
+    // nothing to do this run, so no extra prompt.
+    const force = options.force ?? false;
+    if (force) {
+        const foreignCount = countForceOverwrites(claudeDir, resolveAssetsDir(), installAgents, installHooks);
+        if (foreignCount > 0) {
+            const confirmForce = await prompter.confirm({
+                message: `${foreignCount} archivos ajenos serán sobrescritos por versiones del motor — backup previo en ~/.argos/backups. ¿Continuar?`,
+                initialValue: false
+            });
+            if (prompter.isCancel(confirmForce) || !confirmForce) {
+                prompter.cancel("argos init cancelado — no se tocó nada.");
+                return cancelledInitReport();
+            }
+        }
+    }
+    // Voice activation (spec 0004): if the current settings.json.outputStyle
+    // matches the predecessor harness's voice, ask before taking it over —
+    // this peek is read-only and never writes; the actual takeover only
+    // happens inside runInit below, once the user has confirmed everything.
+    let takeoverNavoriVoice = options.takeoverNavoriVoice ?? true;
+    const currentOutputStyle = peekOutputStyleValue(join(claudeDir, "settings.json"));
+    if (isNavoriOutputStyle(currentOutputStyle)) {
+        const takeover = await prompter.confirm({
+            message: `settings.json.outputStyle apunta a la voz del harness predecesor ('${String(currentOutputStyle)}') — ¿reemplazarla por Argos?`,
+            initialValue: true
+        });
+        if (prompter.isCancel(takeover)) {
+            prompter.cancel("argos init cancelado — no se tocó nada.");
+            return cancelledInitReport();
+        }
+        takeoverNavoriVoice = takeover;
+    }
+    prompter.note([
+        `idioma: ${language}`,
+        `agentes: ${installAgents ? "sí" : "no"}`,
+        "hooks: " + (installHooks ? "sí" : "no"),
+        "skills: sí (siempre — cargan on-demand)",
+        `destino: ${claudeDir}`,
+        "se hace un backup antes de escribir nada"
+    ].join("\n"), "Resumen");
+    const proceed = await prompter.confirm({
+        message: "¿Proceder a escribir estos cambios?",
+        initialValue: true
+    });
+    if (prompter.isCancel(proceed) || !proceed) {
+        prompter.cancel("argos init cancelado — no se tocó nada.");
+        return cancelledInitReport();
+    }
+    const report = runInit({
+        language,
+        installAgents,
+        installHooks,
+        takeoverNavoriVoice,
+        force
+    });
+    prompter.outro(report.summary);
+    return report;
+}
 export const initCommand = defineCommand({
     meta: {
         name: "init",
@@ -323,17 +575,31 @@ export const initCommand = defineCommand({
             ],
             default: "es",
             description: "Idioma del motor (global.json)."
+        },
+        yes: {
+            type: "boolean",
+            default: false,
+            description: "Fuerza modo no interactivo aunque haya una TTY real (defaults + flags, sin wizard)."
+        },
+        force: {
+            type: "boolean",
+            default: false,
+            description: "Sobrescribe con la versión del motor los archivos ajenos (sin marker argos) en agents/skills/output-styles/hooks. No toca prosa ajena de CLAUDE.md ni entradas ajenas de settings.json."
         }
     },
-    run ({ args }) {
-        const report = runInit({
-            language: args.language
+    async run ({ args }) {
+        const report = await runInitInteractive({
+            language: args.language,
+            yes: Boolean(args.yes),
+            force: Boolean(args.force)
         });
         const colorize = (status)=>{
             const padded = status.padEnd(18);
             switch(status){
                 case "skipped-foreign":
                     return pc.yellow(padded);
+                case "overwritten-foreign":
+                    return pc.magenta(padded);
                 case "created":
                     return pc.green(padded);
                 case "updated":