@aiwg/cli 2026.10.5 → 2026.10.6

package/dist/src/discovery/plan-store.js

@@ -0,0 +1,171 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, readFile, rename, rm, stat } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { resolveProjectAiwgDir, resolveProjectAiwgDirForWrite } from '../config/project-artifacts-runtime.mjs';
+import { SETUP_PLAN_SCHEMA_VERSION } from './plan-types.js';
+import { assertPlanRedacted, planIdSchema, validateSetupPlan } from './plan-validation.js';
+function checkedId(id) {
+    assertPlanRedacted(id);
+    if (!planIdSchema.safeParse(id).success)
+        throw new Error('Setup plan ID must be 1-120 letters, digits, underscores, or hyphens, starting with a letter or digit.');
+    return id;
+}
+/** Explicit compatibility seam: pre-release v0 lacked receipts and updatedAt. Never migrate on disk during read. */
+export function migrateSetupPlan(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new Error('Setup plan must be a versioned JSON object.');
+    const value = input;
+    const version = value.schemaVersion;
+    if (typeof version !== 'number' || !Number.isSafeInteger(version) || version < 0) {
+        throw new Error('Setup plan schemaVersion must be a non-negative integer.');
+    }
+    if (version > SETUP_PLAN_SCHEMA_VERSION) {
+        throw new Error(`Setup plan schemaVersion ${version} is newer than supported version ${SETUP_PLAN_SCHEMA_VERSION}; upgrade AIWG before resuming.`);
+    }
+    switch (version) {
+        case 0:
+            return validateSetupPlan({ ...value, schemaVersion: SETUP_PLAN_SCHEMA_VERSION,
+                updatedAt: value.updatedAt === undefined ? value.createdAt : value.updatedAt,
+                receipts: value.receipts === undefined ? [] : value.receipts });
+        case SETUP_PLAN_SCHEMA_VERSION:
+            return validateSetupPlan(value);
+        default:
+            throw new Error('No migration exists for this setup plan schemaVersion.');
+    }
+}
+/** One resolved artifact root owns the entire plan, including receipts for other workspaces. */
+export async function writeSetupPlan(projectDir, input, env) {
+    // Scan the serialized snapshot too: toJSON/getters cannot introduce an unscanned write.
+    assertPlanRedacted(input);
+    let snapshot;
+    try {
+        snapshot = JSON.parse(JSON.stringify(input));
+    }
+    catch {
+        throw new Error('Setup plan must contain serializable JSON values.');
+    }
+    const plan = validateSetupPlan(snapshot);
+    const id = checkedId(plan.id);
+    const root = resolveProjectAiwgDirForWrite(projectDir, env);
+    const destination = join(root, 'setup', 'plans', `${id}.json`);
+    const temporary = join(dirname(destination), `.${id}.${randomUUID()}.tmp`);
+    try {
+        await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
+        const file = await open(temporary, 'wx', 0o600);
+        try {
+            await file.writeFile(JSON.stringify(plan, null, 2) + '\n', 'utf8');
+            await file.sync();
+        }
+        finally {
+            await file.close();
+        }
+        await rename(temporary, destination);
+    }
+    catch (error) {
+        // The error code names the cause (EACCES, ENOSPC, ENOENT) without echoing plan data.
+        const code = error?.code;
+        throw new Error(`Cannot write setup plan under the resolved artifact root${code ? ` (${code})` : ''}. Check that the corpus is attached and writable; no fallback was used.`);
+    }
+    finally {
+        await rm(temporary, { force: true }).catch(() => { });
+    }
+    return destination;
+}
+export async function readSetupPlan(projectDir, id, env) {
+    checkedId(id);
+    const root = resolveProjectAiwgDir(projectDir, env);
+    try {
+        if (!(await stat(root)).isDirectory())
+            throw new Error();
+    }
+    catch {
+        throw new Error('Resolved AIWG artifact root is unavailable. Reconnect or attach the corpus before reading setup plans; no fallback was used.');
+    }
+    let content;
+    try {
+        content = await readFile(join(root, 'setup', 'plans', `${id}.json`), 'utf8');
+    }
+    catch {
+        throw new Error('Cannot read setup plan from the resolved artifact root. Check the plan ID and file permissions; no fallback was used.');
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch {
+        throw new Error('Setup plan is not valid JSON. Restore the plan from a valid copy.');
+    }
+    const plan = migrateSetupPlan(parsed);
+    if (plan.id !== id)
+        throw new Error('Setup plan ID does not match its filename.');
+    return plan;
+}
+/** Failed and skipped actions remain eligible. The apply slice decides retry/skip policy. */
+export function remainingPlanActions(plan) {
+    return plan.actions.filter(action => !plan.receipts.some(receipt => receipt.workspace === action.workspace &&
+        Object.hasOwn(receipt.actions, action.id) && receipt.actions[action.id].status === 'applied'));
+}
+/** Presence counts, including false, null, and default/discovered answers. Never fill/overwrite answers here. */
+export function unansweredPlanChoices(plan) {
+    return plan.unresolvedChoices.filter(choice => !Object.hasOwn(plan.answers, choice.questionId));
+}
+function observedPaths(project) {
+    return [project.root, project.packageManifest, ...project.packageRoots,
+        project.aiwg.directory ? join(project.root, '.aiwg') : null, project.aiwg.configFile,
+        project.aiwg.contextFile, ...project.providerFiles.map(file => file.path)].filter((path) => path !== null);
+}
+function factValue(inventory, fact) {
+    if (fact.kind === 'tool')
+        return inventory.tools.find(tool => tool.executable === fact.executable)?.[fact.field];
+    const root = fact.kind === 'project' ? fact.root : fact.workspace;
+    const project = inventory.projects.find(entry => entry.root === root);
+    if (fact.kind === 'project')
+        return project?.[fact.field];
+    if (project && observedPaths(project).includes(fact.path))
+        return true;
+    // Missing observations in a partial inventory cannot establish absence.
+    if (inventory.stats.truncated || inventory.diagnostics.some(d => ['inaccessible', 'symlink-skipped', 'outside-root'].includes(d.code)))
+        return undefined;
+    return false;
+}
+/** Successful config owners establish these paths as present for subsequent actions. */
+function createdByAppliedConfig(plan, fact) {
+    if (fact.kind !== 'path' || ![join(fact.workspace, '.aiwg'), join(fact.workspace, '.aiwg', 'aiwg.config')].includes(fact.path))
+        return false;
+    return plan.actions.some(action => action.workspace === fact.workspace &&
+        ['write-project-config', 'configure-worker-dispatch', 'record-decline'].includes(action.kind) &&
+        plan.receipts.some(receipt => receipt.workspace === action.workspace && receipt.actions[action.id]?.status === 'applied'));
+}
+/** Pure comparison of local observations. Does not inspect paths, execute tools, or authorize apply. */
+export function revalidateSetupPlan(plan, fresh) {
+    return plan.actions.flatMap(action => {
+        const changes = action.dependsOn.flatMap(fact => {
+            const before = createdByAppliedConfig(plan, fact) ? true : factValue(plan.inventory, fact);
+            const after = factValue(fresh, fact);
+            let reason;
+            if (before === undefined || after === undefined || before === 'unknown' || after === 'unknown')
+                reason = 'unobserved';
+            if (fact.kind === 'tool') {
+                const tool = fresh.tools.find(entry => entry.executable === fact.executable);
+                if (!tool || tool.installed === 'unknown')
+                    reason = 'unobserved';
+                else if (tool.installed === 'no')
+                    reason = 'tool-not-installed';
+                else if (fact.field === 'version' && (before === null || after === null))
+                    reason = 'unobserved';
+                else if (fact.field === 'version' && !isDeepStrictEqual(before, after))
+                    reason = 'version-changed';
+            }
+            if (fact.kind === 'project' && before !== undefined && after === undefined && !fresh.stats.truncated &&
+                !fresh.diagnostics.some(d => d.path === fact.root && d.code === 'inaccessible'))
+                reason = 'path-missing';
+            if (!reason && !isDeepStrictEqual(before, after)) {
+                reason = fact.kind === 'path' && after === false ? 'path-missing' : 'fact-changed';
+            }
+            return reason ? [{ fact, reason, before: before, after: after }] : [];
+        });
+        return changes.length ? [{ actionId: action.id, workspace: action.workspace, changes }] : [];
+    });
+}
+//# sourceMappingURL=plan-store.js.map

package/dist/src/discovery/plan-types.js

@@ -0,0 +1,2 @@
+export const SETUP_PLAN_SCHEMA_VERSION = 1;
+//# sourceMappingURL=plan-types.js.map

package/dist/src/discovery/plan-validation.js

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { dateTime, number } from '../schema/zod-validation.mjs';
+import { redactText } from '../governance/redaction.js';
+import { SETUP_PLAN_SCHEMA_VERSION } from './plan-types.js';
+const text = z.string().min(1);
+const timestamp = dateTime({ offset: true });
+const observation = z.enum(['yes', 'no', 'unknown']);
+export const planIdSchema = text.max(120).regex(/^[a-zA-Z0-9][a-zA-Z0-9_-]*$/);
+const referenceSchema = z.strictObject({
+    kind: z.literal('credential-ref'), source: z.enum(['env', 'file', 'stdin-at-apply']), name: text,
+});
+const valueSchema = z.lazy(() => z.union([
+    z.string(), z.number().finite(), z.boolean(), z.null(), z.array(valueSchema), z.record(z.string(), valueSchema),
+]));
+const projectSchema = z.strictObject({
+    root: text, sources: z.array(z.enum(['workspace', 'registry', 'selected'])),
+    vcs: z.enum(['git', 'worktree', 'none', 'unknown']), layout: z.enum(['project', 'package', 'monorepo', 'ambiguous']),
+    packageManifest: text.nullable(), workspacePatterns: z.array(z.string()), packageRoots: z.array(text),
+    aiwg: z.strictObject({ directory: z.boolean(), configFile: text.nullable(), contextFile: text.nullable() }),
+    providerFiles: z.array(z.strictObject({ provider: text, path: text, kind: z.enum(['config', 'context', 'artifacts']) })),
+});
+const toolSchema = z.strictObject({
+    executable: text, path: text.nullable(), installed: observation, configured: observation,
+    authenticated: observation, qualified: observation, version: text.nullable(), evidence: z.array(z.string()),
+});
+const inventorySchema = z.strictObject({
+    projects: z.array(projectSchema), tools: z.array(toolSchema),
+    diagnostics: z.array(z.strictObject({
+        code: z.enum(['depth-limit', 'entry-limit', 'time-limit', 'file-limit', 'inaccessible', 'invalid-metadata',
+            'symlink-skipped', 'outside-root', 'ambiguous', 'excluded', 'home-scan-refused']),
+        path: z.string(), message: z.string(),
+    })),
+    limits: z.strictObject({ maxDepth: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }), maxEntries: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }),
+        timeBudgetMs: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }), maxFileBytes: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }) }),
+    stats: z.strictObject({ entriesInspected: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }), elapsedMs: number().check(z.gte(0)).meta({ type: 'number', minimum: 0 }), truncated: z.boolean() }),
+});
+const factSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('project'), root: text, field: projectSchema.keyof() }),
+    z.strictObject({ kind: z.literal('tool'), executable: text, field: toolSchema.keyof() }),
+    z.strictObject({ kind: z.literal('path'), workspace: text, path: text }),
+]);
+const planSchema = z.strictObject({
+    schemaVersion: z.literal(SETUP_PLAN_SCHEMA_VERSION), id: planIdSchema, inventoryId: text,
+    createdAt: timestamp, updatedAt: timestamp,
+    answers: z.record(z.string(), z.strictObject({ value: valueSchema,
+        source: z.enum(['explicit-flag', 'existing-setting', 'interview', 'default', 'discovered']), answeredAt: timestamp })),
+    recommendations: z.array(z.strictObject({ questionId: text, value: valueSchema, reason: text })),
+    unresolvedChoices: z.array(z.strictObject({ questionId: text,
+        options: z.array(z.strictObject({ label: text, value: valueSchema })).min(1),
+        default: valueSchema, whyItMatters: text, deferredAt: timestamp.optional() })),
+    actions: z.array(z.strictObject({ id: text, workspace: text, provider: text, scope: z.enum(['project', 'user']),
+        kind: text, dependsOn: z.array(factSchema) })),
+    receipts: z.array(z.strictObject({ workspace: text, actions: z.record(z.string(), z.strictObject({
+            status: z.enum(['applied', 'failed', 'skipped']), startedAt: timestamp, completedAt: timestamp,
+            message: z.string().optional(),
+        })) })),
+    inventory: inventorySchema,
+});
+const sensitiveKey = /(?:password|passwd|token|secret|api[_-]?key|credential|authorization|cookie|private[_-]?key|connection[_-]?string)/i;
+const secretError = () => new Error('Setup plan contains secret-looking material; use a credential-ref (env, file, or stdin-at-apply).');
+/** Scan the exact JSON snapshot, including keys and free-form evidence/messages. Never echo rejected values. */
+export function assertPlanRedacted(input) {
+    let nodes = 0;
+    const scanText = (value) => {
+        const result = redactText(value, { organizationPatterns: [
+                { id: 'jwt', pattern: '\\beyJ[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]+\\.[A-Za-z0-9_-]{8,}\\b' },
+                { id: 'extra-token', pattern: '\\b(?:aiwg_(?:at|rt)_|npm_|hf_|xai-|AIza)[A-Za-z0-9_-]{8,}\\b' },
+            ] });
+        if (result.sensitivity !== 'none')
+            throw secretError();
+        // Scan disjoint runs rather than retrying lookaheads at every word boundary.
+        for (const candidate of value.match(/[A-Za-z0-9_+=-]{32,}/g) ?? []) {
+            if (/[a-z]/.test(candidate) && /[A-Z]/.test(candidate) && /[0-9]/.test(candidate))
+                throw secretError();
+        }
+    };
+    const isReference = (value) => referenceSchema.safeParse(value).success;
+    const visit = (value, depth, answerMap = false) => {
+        if (++nodes > 100_000 || depth > 64)
+            throw new Error('Setup plan exceeds redaction structure limits.');
+        if (typeof value === 'string')
+            scanText(value);
+        if (!value || typeof value !== 'object')
+            return;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item, depth + 1);
+            return;
+        }
+        const object = value;
+        if (object.kind === 'credential-ref' && !isReference(object))
+            throw secretError();
+        // Answers and recommendations can carry sensitive question IDs as data.
+        if (typeof object.questionId === 'string' && sensitiveKey.test(object.questionId)) {
+            const values = [object.value, object.default,
+                ...(Array.isArray(object.options) ? object.options.map(option => option?.value) : [])];
+            if (values.some(candidate => candidate !== undefined && candidate !== null && !isReference(candidate)))
+                throw secretError();
+        }
+        for (const [key, child] of Object.entries(object)) {
+            scanText(key);
+            if (sensitiveKey.test(key) && child !== null && child !== undefined && !isReference(child)) {
+                // A sensitive answer ID may wrap a reference with source/timestamp metadata.
+                const answer = child && typeof child === 'object' ? child : null;
+                if (!answerMap || !answer || !Object.hasOwn(answer, 'value') ||
+                    (answer.value !== null && !isReference(answer.value)))
+                    throw secretError();
+            }
+            visit(child, depth + 1, depth === 0 && key === 'answers');
+        }
+    };
+    visit(input, 0);
+}
+export function validateSetupPlan(input) {
+    assertPlanRedacted(input);
+    const parsed = planSchema.safeParse(input);
+    // Zod errors can include credential-bearing keys/values: keep diagnostics structural.
+    if (!parsed.success)
+        throw new Error('Invalid setup plan v1 shape; check required fields, timestamps, and action dependencies.');
+    const plan = parsed.data;
+    const ids = new Set(plan.actions.map(action => action.id));
+    if (ids.size !== plan.actions.length)
+        throw new Error('Setup plan action IDs must be unique.');
+    if (new Set(plan.receipts.map(receipt => receipt.workspace)).size !== plan.receipts.length) {
+        throw new Error('Setup plan workspace receipts must be unique.');
+    }
+    for (const receipt of plan.receipts)
+        for (const [id, result] of Object.entries(receipt.actions)) {
+            if (!plan.actions.some(action => action.id === id && action.workspace === receipt.workspace)) {
+                throw new Error('Setup plan receipt must refer to an action in the same workspace.');
+            }
+            if (Date.parse(result.completedAt) < Date.parse(result.startedAt))
+                throw new Error('Setup plan receipt timestamps are out of order.');
+        }
+    if (Date.parse(plan.updatedAt) < Date.parse(plan.createdAt))
+        throw new Error('Setup plan timestamps are out of order.');
+    return plan;
+}
+//# sourceMappingURL=plan-validation.js.map

package/dist/src/discovery/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/src/extensions/commands/definitions.js

@@ -687,6 +687,7 @@ export const initCommand = {
         triggerPhrases: ['init project', 'setup project config', 'configure providers'],
         commandHint: {
             template: 'utility',
+            argumentHint: '[--scope project|user] [--intent code|docs|ops|mixed] [--credential <provider>=env:NAME|file:PATH|stdin] [--jev enable|decline|defer]',
             allowedTools: ['Read', 'Write'],
         },
     },
@@ -718,7 +719,7 @@ export const setupCommand = {
         ],
         commandHint: {
             template: 'utility',
-            argumentHint: 'project [--yes] [--dry-run] [--target <dir>]',
+            argumentHint: 'project [--yes] [--dry-run] [--review] [--apply] [--plan <id>] [--target <dir>] [--scope project|user] [--workspace <root>] [--monorepo root|package] [--package <root>] [--scan-roots <dir>] [--intent code|docs|ops|mixed] [--credential <provider>=env:NAME|file:PATH|stdin] [--jev enable|decline|defer]',
             allowedTools: ['Read', 'Write', 'Bash'],
         },
     },
@@ -1647,14 +1648,14 @@ export const discoverCommand = {
     },
 };
 // Show: companion to `discover`. Where `discover` ranks candidates,
-// `show` fetches the full body of one specific artifact (#1218). This
+// `show` returns a metadata card with explicit section/body drill-ins. This
 // closes the loop so consumers never need to navigate AIWG's storage
 // paths themselves — the CLI is the access point.
 export const showCommand = {
     id: 'show',
     type: 'skill',
     name: 'Show',
-    description: 'Print the full text of a specific AIWG skill, agent, command, or rule by name',
+    description: 'Show an AIWG artifact metadata card; use --section or --body for content',
     version: '1.0.0',
     capabilities: ['cli', 'discovery', 'read', 'capability', 'skills'],
     keywords: ['show', 'cat', 'read skill', 'print skill', 'get skill content', 'aiwg show'],
@@ -1678,7 +1679,7 @@ export const showCommand = {
         ],
         commandHint: {
             template: 'utility',
-            argumentHint: '<type> <name> [--json] [--first] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]   # type: skill | agent | command | rule',
+            argumentHint: '<type> <name> [--body] [--section <heading>] [--rules] [--resources] [--json] [--first] [--resource-source local|web|auto] [--aiwg-version <version|range|digest|channel>] [--offline]   # type: skill | agent | command | rule',
             allowedTools: ['Read'],
         },
     },
@@ -3177,6 +3178,39 @@ export const daemonInitCommand = {
         },
     },
 };
+export const housekeeperCommand = {
+    id: 'housekeeper',
+    type: 'skill',
+    name: 'Housekeeper',
+    description: 'Deterministic maintenance daemon: start/stop/status/run-once, jobs, watch roots, autostart units',
+    version: '1.0.0',
+    capabilities: ['cli', 'daemon', 'maintenance', 'scheduler'],
+    keywords: ['housekeeper', 'daemon', 'maintenance', 'schedule', 'run-once', 'autostart'],
+    category: 'daemon',
+    platforms: {
+        claude: 'full',
+        generic: 'full',
+    },
+    deployment: {
+        pathTemplate: '.{platform}/commands/{id}.md',
+        core: false,
+    },
+    metadata: {
+        type: 'skill',
+        triggerPhrases: ['housekeeper', 'housekeeper status', 'housekeeper start', 'maintenance daemon'],
+        commandHint: {
+            template: 'utility',
+            argumentHint: '<start|stop|status|run-once|job|watch|install|uninstall> [options]',
+            allowedTools: ['Bash', 'Read', 'Write'],
+            executionSteps: [
+                'Parse subcommand and flags',
+                'Start/stop/query the housekeeper-profile daemon or edit its config',
+                'Run one job without a daemon (run-once) or write autostart units (install)',
+                'Display result',
+            ],
+        },
+    },
+};
 // Config Commands
 export const configCommand = {
     id: 'config',
@@ -3341,7 +3375,7 @@ export const memoryCommand = {
     id: 'memory',
     type: 'skill',
     name: 'Memory',
-    description: 'Storage operations on the AIWG memory subsystem, plus user-level project memory registry commands under ~/.aiwg/projects',
+    description: 'Read-only memory audit/cost/recommend/verify, reviewed plan/apply/restore, storage and project memory registry commands',
     version: '1.0.0',
     capabilities: ['cli', 'memory', 'semantic-memory', 'storage', 'pkm', 'project-memory', 'user-registry'],
     keywords: ['memory', 'semantic-memory', 'project-memory', 'registry', 'reflections', 'pages'],
@@ -3359,11 +3393,16 @@ export const memoryCommand = {
         triggerPhrases: ['where is memory', 'memory path', 'list memory', 'project memory', 'aiwg memory'],
         commandHint: {
             template: 'utility',
-            argumentHint: '<path|list|get|put|delete|append-log|project> [options]',
+            argumentHint: '<audit|cost|recommend|plan|apply|verify|restore|path|list|get|put|delete|append-log|project> [options]',
             allowedTools: ['Bash', 'Read'],
             executionSteps: [
                 'Parse subcommand and arguments',
-                'Resolve storage adapter for memory subsystem',
+                'For audit, parse --scope global|project|provider, --provider <id>, --json, --cost strictly; default to workspace and perform a bounded read-only inventory',
+                'For cost, run the same read-only inventory through the resident-cost view (--demote, --startup-measurement, --usage only read; nothing is written)',
+                'For recommend and verify, run read-only reports; verify --plan checks existing owner receipts, retained history and published end states without refresh',
+                'For plan/apply/restore, show project targeting, diff, owner review and next-session limits; mutation requires exact reviewed owner plans',
+                'Use maintenance exit codes 0 success, 1 findings, 2 usage, 3 stale or failed',
+                'Resolve storage adapter for storage operations only',
                 'Read/write/list/delete/append-log via the adapter or manage project-memory mappings',
                 'Print result',
             ],
@@ -3755,7 +3794,7 @@ export const rlmCacheCommand = {
  * - SDLC Orchestration (1): sdlc-accelerate
  * - Index (1): index
  * - Reproducibility (4): execution-mode, snapshot, checkpoint, reproducibility-validate
- * - Daemon (2): behavior, daemon-init
+ * - Daemon (3): behavior, daemon-init, housekeeper
  * - Config (1): config
  * - Ops (1): ops
  * - Agentic Tools (5): chunk, fanout, rlm-prep, rlm-search, rlm-status
@@ -3886,9 +3925,10 @@ export const commandDefinitions = [
     snapshotCommand,
     checkpointCommand,
     reproducibilityValidateCommand,
-    // Daemon (2)
+    // Daemon (3)
     behaviorCommand,
     daemonInitCommand,
+    housekeeperCommand,
     // Config (1)
     configCommand,
     // Ops (1)