@angelmsger/fx 0.0.0-stage → 0.11.0

package/dist/application/docs/derive.js

@@ -0,0 +1,101 @@
+// Derive the marked workspace guide while preserving foreign files.
+import path from 'node:path';
+import { CLAUDE_GUIDE, derive, isDerived } from '../../domain/docs/derived.js';
+import { completeRegions } from '../../domain/docs/regions.js';
+import { agentsSkeleton } from '../../domain/docs/skeleton.js';
+import { renderAll } from '../../domain/docs/templates.js';
+import { assertWritable } from '../safety/posture.js';
+import { actionFor, documentPath, finish, pending, reportRegions, } from './rendered.js';
+import { templateInputOf } from './template.js';
+export class DeriveDocs {
+    deps;
+    login;
+    constructor(deps, login) {
+        this.deps = deps;
+        this.login = login;
+    }
+    async execute(input) {
+        const { ctx, fs, reporter } = this.deps;
+        const origin = path.join(ctx.manifestDir, 'AGENTS.md');
+        const source = (await fs.readText(origin)) ?? agentsSkeleton(ctx.name);
+        const rendered = completeRegions(source, renderAll(await templateInputOf(ctx.context, this.login, fs)));
+        const agents = await this.file(input.out ?? path.join(ctx.root, 'AGENTS.md'), derive(await this.sourceLinks(rendered.text), origin), rendered);
+        reportRegions(reporter, origin, agents.file);
+        const files = [agents];
+        if (input.out === undefined)
+            files.push(...(await this.retiredPointer()));
+        const conflicts = files.filter((f) => f.file.action === 'foreign');
+        if (!input.dryRun && !input.check && input.replace !== undefined && conflicts.length > 0) {
+            assertWritable(input.posture, 'replace workspace documents');
+            if (await input.replace(conflicts.map((f) => f.file.path))) {
+                for (const conflict of conflicts) {
+                    const index = files.indexOf(conflict);
+                    files[index] = {
+                        ...conflict,
+                        before: { kind: 'absent', text: null },
+                        file: { ...conflict.file, action: 'updated', result: 'planned' },
+                    };
+                }
+            }
+        }
+        const foreign = files.filter((f) => f.file.action === 'foreign');
+        if (foreign.length > 0)
+            reporter.notice({
+                code: 'DOCS_FOREIGN',
+                message: `${foreign.map((f) => f.file.path).join(', ')} ${foreign.length === 1 ? 'was' : 'were'} not written by fx and left alone`,
+                nextSteps: ['Move the file aside if fx should own it, then `fx sync --only docs`.'],
+            });
+        const output = await finish(this.deps.projections, input, files);
+        const removed = output.files.find((f) => f.action === 'removed' && f.result === 'done');
+        if (removed !== undefined)
+            reporter.notice({
+                code: 'DOCS_POINTER_REMOVED',
+                message: `${removed.path} was removed: Claude Code reads AGENTS.md without the pointer`,
+            });
+        return output;
+    }
+    // A relative link means a file of the manifest source, as long as one is there;
+    // the derived guide sits elsewhere, so it gets the resolved path.
+    async sourceLinks(text) {
+        const { manifestDir } = this.deps.ctx;
+        const links = [...text.matchAll(/\]\((<?)((?![#/~]|[a-z][\w+.-]*:)[^)#>]+)([^)]*)\)/gi)];
+        for (const match of links) {
+            const target = path.resolve(manifestDir, decodeLink(match[2]));
+            const relative = path.relative(manifestDir, target);
+            const outside = relative === '..' || relative.startsWith(`..${path.sep}`);
+            if (relative === '' || outside || path.isAbsolute(relative))
+                continue;
+            if (!(await this.deps.fs.exists(target)))
+                continue;
+            const suffix = match[3].replace(/>$/, '');
+            // Markdown reads a backslash before punctuation as an escape (`\.fx` loses
+            // its backslash), so a Windows path is linked with forward slashes, which
+            // Windows also accepts.
+            const link = target.split(path.sep).join('/');
+            text = text.replace(match[0], `](<${link}${suffix}>)`);
+        }
+        return text;
+    }
+    async file(target, text, regions) {
+        const before = await this.deps.projections.read(documentPath(target));
+        const current = before.text ?? undefined;
+        const foreign = before.kind === 'foreign' || (current !== undefined && !isDerived(current));
+        return pending(target, foreign ? 'foreign' : actionFor(current, text), text, before, regions);
+    }
+    async retiredPointer() {
+        const target = path.join(this.deps.ctx.root, CLAUDE_GUIDE);
+        const before = await this.deps.projections.read(documentPath(target));
+        if (before.text === null || !isDerived(before.text))
+            return [];
+        return [pending(target, 'removed', null, before)];
+    }
+}
+function decodeLink(value) {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+}
+//# sourceMappingURL=derive.js.map

package/dist/application/docs/derive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"derive.js","sourceRoot":"","sources":["../../../src/application/docs/derive.ts"],"names":[],"mappings":"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"}

package/dist/application/docs/render-regions.js

@@ -0,0 +1,39 @@
+// Rendering the generated regions of AGENTS.md inside a checkout of the manifest
+// repository, for its maintainers and its CI. Prose outside the regions is preserved
+// using a captured snapshot; a draft may target another path.
+import path from 'node:path';
+import { renderRegions } from '../../domain/docs/regions.js';
+import { agentsSkeleton } from '../../domain/docs/skeleton.js';
+import { renderAll } from '../../domain/docs/templates.js';
+import { actionFor, documentPath, documentConflict, finish, pending, reportRegions, } from './rendered.js';
+import { templateInputOf } from './template.js';
+export class RenderRegions {
+    deps;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    async execute(input) {
+        const agents = await this.agents(input.out);
+        reportRegions(this.deps.reporter, agents.file.path, agents.file);
+        const result = await finish(this.deps.projections, input, [agents]);
+        if (result.files[0]?.action === 'created' && result.files[0].result === 'done')
+            this.deps.reporter.notice({
+                code: 'DOCS_CREATED',
+                message: `${agents.file.path} did not exist; a skeleton with every region was written`,
+            });
+        return result;
+    }
+    async agents(out) {
+        const source = path.join(this.deps.context.dir, 'AGENTS.md');
+        const target = out ?? source;
+        // A draft written elsewhere is always fresh: the skeleton, fully rendered.
+        const before = await this.deps.projections.read(documentPath(target));
+        if (before.kind === 'foreign')
+            throw documentConflict(target);
+        const existing = out === undefined ? (before.text ?? undefined) : undefined;
+        const base = existing ?? agentsSkeleton(path.basename(this.deps.context.dir));
+        const rendered = renderRegions(base, renderAll(await templateInputOf(this.deps.context, this.deps, this.deps.fs)));
+        return pending(target, actionFor(before.text ?? undefined, rendered.text), rendered.text, before, rendered);
+    }
+}
+//# sourceMappingURL=render-regions.js.map

package/dist/application/docs/render-regions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"render-regions.js","sourceRoot":"","sources":["../../../src/application/docs/render-regions.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,qFAAqF;AACrF,8DAA8D;AAE9D,OAAO,IAAI,MAAM,WAAW,CAAC;AAE7B,OAAO,EAAE,aAAa,EAAE,MAAM,8BAA8B,CAAC;AAC7D,OAAO,EAAE,cAAc,EAAE,MAAM,+BAA+B,CAAC;AAC/D,OAAO,EAAE,SAAS,EAAE,MAAM,gCAAgC,CAAC;AAO3D,OAAO,EACL,SAAS,EACT,YAAY,EACZ,gBAAgB,EAChB,MAAM,EACN,OAAO,EACP,aAAa,GAId,MAAM,eAAe,CAAC;AACvB,OAAO,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAShD,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,IAAuB;QAAvB,SAAI,GAAJ,IAAI,CAAmB;IAAG,CAAC;IAExD,KAAK,CAAC,OAAO,CAAC,KAAkB;QAC9B,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;QAC5C,aAAa,CAAC,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,IAAI,CAAC,CAAC;QACjE,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,WAAW,EAAE,KAAK,EAAE,CAAC,MAAM,CAAC,CAAC,CAAC;QACpE,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,MAAM,KAAK,SAAS,IAAI,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,KAAK,MAAM;YAC5E,IAAI,CAAC,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC;gBACxB,IAAI,EAAE,cAAc;gBACpB,OAAO,EAAE,GAAG,MAAM,CAAC,IAAI,CAAC,IAAI,0DAA0D;aACvF,CAAC,CAAC;QACL,OAAO,MAAM,CAAC;IAChB,CAAC;IAEO,KAAK,CAAC,MAAM,CAAC,GAAuB;QAC1C,MAAM,MAAM,GAAG,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,EAAE,WAAW,CAAC,CAAC;QAC7D,MAAM,MAAM,GAAG,GAAG,IAAI,MAAM,CAAC;QAC7B,2EAA2E;QAC3E,MAAM,MAAM,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,CAAC,CAAC,CAAC;QACtE,IAAI,MAAM,CAAC,IAAI,KAAK,SAAS;YAAE,MAAM,gBAAgB,CAAC,MAAM,CAAC,CAAC;QAC9D,MAAM,QAAQ,GAAG,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,IAAI,SAAS,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;QAC5E,MAAM,IAAI,GAAG,QAAQ,IAAI,cAAc,CAAC,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC;QAC9E,MAAM,QAAQ,GAAG,aAAa,CAC5B,IAAI,EACJ,SAAS,CAAC,MAAM,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,OAAO,EAAE,IAAI,CAAC,IAAI,EAAE,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC,CAC7E,CAAC;QACF,OAAO,OAAO,CACZ,MAAM,EACN,SAAS,CAAC,MAAM,CAAC,IAAI,IAAI,SAAS,EAAE,QAAQ,CAAC,IAAI,CAAC,EAClD,QAAQ,CAAC,IAAI,EACb,MAAM,EACN,QAAQ,CACT,CAAC;IACJ,CAAC;CACF"}

package/dist/application/docs/rendered.js

@@ -0,0 +1,91 @@
+// Apply document plans against captured snapshots and retain per-file outcomes
+// when a later write fails. A planned action is not evidence of a completed write.
+import path from 'node:path';
+import { begin, end } from '../../domain/docs/regions.js';
+import { asDevkitError, DevkitError, toEnvelope, withPartialResult, } from '../../domain/errors.js';
+import { assertWritable } from '../safety/posture.js';
+const CHANGES = new Set(['created', 'updated', 'removed']);
+export function actionFor(current, next) {
+    if (current === undefined)
+        return 'created';
+    return current === next ? 'unchanged' : 'updated';
+}
+export function pending(path, action, text, before, regions) {
+    return {
+        text,
+        before,
+        file: {
+            path,
+            action,
+            result: CHANGES.has(action) ? 'planned' : 'skipped',
+            replaced: regions?.replaced ?? [],
+            missing: regions?.missing ?? [],
+            added: regions?.added ?? [],
+            unknown: regions?.unknown ?? [],
+        },
+    };
+}
+export function reportRegions(reporter, source, file) {
+    for (const name of file.missing) {
+        reporter.notice({
+            code: 'DOCS_REGION_MISSING',
+            message: `${source} has no "${name}" region; paste these markers where it belongs and render again`,
+            nextSteps: [begin(name), end(name)],
+        });
+    }
+    for (const name of file.unknown)
+        reporter.notice({
+            code: 'DOCS_REGION_UNKNOWN',
+            message: `${source} contained a "${name}" region this fx does not generate; only standalone retired blocks are removed`,
+        });
+}
+export async function finish(store, input, files) {
+    const output = { files: files.map((f) => f.file) };
+    const stale = files.filter((f) => CHANGES.has(f.file.action));
+    if (input.check) {
+        if (stale.length === 0)
+            return output;
+        throw new DevkitError('conflict', 'DOCS_STALE', `${stale.map((f) => f.file.path).join(', ')} differ${stale.length === 1 ? 's' : ''} from the manifest`, {
+            hint: 'The generated regions no longer match the manifest.',
+            nextSteps: ['fx sync --only docs', 'fx manifest render'],
+        });
+    }
+    if (input.dryRun || stale.length === 0)
+        return output;
+    assertWritable(input.posture, 'docs');
+    for (const f of stale) {
+        const index = files.indexOf(f);
+        try {
+            const result = await store.write({
+                ...documentPath(f.file.path),
+                before: f.before,
+                text: f.text,
+            });
+            if (result === 'busy' || result === 'conflict')
+                throw documentConflict(f.file.path);
+            output.files[index] = { ...f.file, result: result === 'written' ? 'done' : 'skipped' };
+        }
+        catch (error) {
+            const failure = toEnvelope(asDevkitError(error)).error;
+            output.files[index] = { ...f.file, result: 'failed', failure };
+            for (let pending = index + 1; pending < output.files.length; pending++) {
+                const file = output.files[pending];
+                if (file.result === 'planned')
+                    output.files[pending] = { ...file, result: 'not_started' };
+            }
+            throw withPartialResult(error, output);
+        }
+    }
+    return output;
+}
+export function documentPath(file) {
+    const absolute = path.resolve(file);
+    return { root: path.dirname(absolute), relative: path.basename(absolute) };
+}
+export function documentConflict(file) {
+    return new DevkitError('conflict', 'DOCS_WRITE_CONFLICT', `The document changed or cannot be safely replaced: ${file}`, {
+        hint: 'Concurrent edits and non-regular paths are preserved.',
+        nextSteps: ['Inspect the reported path, then preview and retry the same docs command.'],
+    });
+}
+//# sourceMappingURL=rendered.js.map

package/dist/application/docs/rendered.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rendered.js","sourceRoot":"","sources":["../../../src/application/docs/rendered.ts"],"names":[],"mappings":"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"}

package/dist/application/docs/skill-catalog.js

@@ -0,0 +1,18 @@
+// Read team Skill metadata for both source and derived guide rendering.
+import path from 'node:path';
+import { parseFrontmatter } from '../../domain/skills/frontmatter.js';
+import { teamSkills } from '../skill/observe.js';
+export async function skillCatalog(fs, manifestDir) {
+    const entries = [];
+    for (const skill of await teamSkills(fs, manifestDir)) {
+        const text = await fs.readText(path.join(skill.dir, 'SKILL.md'));
+        const front = parseFrontmatter(text ?? '');
+        entries.push({
+            name: front.name ?? skill.name,
+            description: front.description ?? 'No description provided; inspect this Skill before selecting it.',
+            source: `skills/${skill.name}/SKILL.md`,
+        });
+    }
+    return entries;
+}
+//# sourceMappingURL=skill-catalog.js.map

package/dist/application/docs/skill-catalog.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"skill-catalog.js","sourceRoot":"","sources":["../../../src/application/docs/skill-catalog.ts"],"names":[],"mappings":"AAAA,wEAAwE;AAExE,OAAO,IAAI,MAAM,WAAW,CAAC;AAG7B,OAAO,EAAE,gBAAgB,EAAE,MAAM,oCAAoC,CAAC;AAEtE,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAEjD,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,EAAc,EAAE,WAAmB;IACpE,MAAM,OAAO,GAAqB,EAAE,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,MAAM,UAAU,CAAC,EAAE,EAAE,WAAW,CAAC,EAAE,CAAC;QACtD,MAAM,IAAI,GAAG,MAAM,EAAE,CAAC,QAAQ,CAAC,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,GAAG,EAAE,UAAU,CAAC,CAAC,CAAC;QACjE,MAAM,KAAK,GAAG,gBAAgB,CAAC,IAAI,IAAI,EAAE,CAAC,CAAC;QAC3C,OAAO,CAAC,IAAI,CAAC;YACX,IAAI,EAAE,KAAK,CAAC,IAAI,IAAI,KAAK,CAAC,IAAI;YAC9B,WAAW,EACT,KAAK,CAAC,WAAW,IAAI,kEAAkE;YACzF,MAAM,EAAE,UAAU,KAAK,CAAC,IAAI,WAAW;SACxC,CAAC,CAAC;IACL,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC"}

package/dist/application/docs/template.js

@@ -0,0 +1,15 @@
+// Everything the templates read, taken from one loaded manifest.
+import { toolsOf } from '../tool/toolchain.js';
+import { skillCatalog } from './skill-catalog.js';
+export async function templateInputOf(context, login, fs) {
+    return {
+        teamSkills: await skillCatalog(fs, context.dir),
+        workspace: context.bundle.workspace.result.doc,
+        environments: context.bundle.environments?.result.doc,
+        bindings: context.bindings,
+        platforms: context.platforms,
+        tools: toolsOf(context.bundle),
+        toolsOf: (provider) => login.describeProvider(provider)?.tools ?? [provider],
+    };
+}
+//# sourceMappingURL=template.js.map

package/dist/application/docs/template.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"template.js","sourceRoot":"","sources":["../../../src/application/docs/template.ts"],"names":[],"mappings":"AAAA,iEAAiE;AAMjE,OAAO,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAE/C,OAAO,EAAE,YAAY,EAAE,MAAM,oBAAoB,CAAC;AAElD,MAAM,CAAC,KAAK,UAAU,eAAe,CACnC,OAAwB,EACxB,KAA0C,EAC1C,EAAc;IAEd,OAAO;QACL,UAAU,EAAE,MAAM,YAAY,CAAC,EAAE,EAAE,OAAO,CAAC,GAAG,CAAC;QAC/C,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,SAAS,CAAC,MAAM,CAAC,GAAG;QAC9C,YAAY,EAAE,OAAO,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,GAAG;QACrD,QAAQ,EAAE,OAAO,CAAC,QAAQ;QAC1B,SAAS,EAAE,OAAO,CAAC,SAAS;QAC5B,KAAK,EAAE,OAAO,CAAC,OAAO,CAAC,MAAM,CAAC;QAC9B,OAAO,EAAE,CAAC,QAAgB,EAAE,EAAE,CAAC,KAAK,CAAC,gBAAgB,CAAC,QAAQ,CAAC,EAAE,KAAK,IAAI,CAAC,QAAQ,CAAC;KACrF,CAAC;AACJ,CAAC"}

package/dist/application/doctor/agents.js

@@ -0,0 +1,33 @@
+// Check required Skill projections for enabled agents. Installation evidence does
+// not establish that the host has activated a Skill.
+import { repairAction } from '../preparation.js';
+import { SkillList } from '../skill/list.js';
+import { workspaceCommand } from '../workspace/guidance.js';
+import { finding } from './types.js';
+export async function checkAgents(deps, skills) {
+    const rows = await new SkillList(deps, skills).execute({});
+    const findings = [];
+    const fix = workspaceCommand(deps, 'sync', '--only', 'skills');
+    for (const row of rows) {
+        for (const [agent, state] of Object.entries(row.states)) {
+            const id = `${agent}:${row.name}`;
+            if (state === 'installed')
+                findings.push(finding('agents', id, 'ok', 'installed'));
+            else if (state === 'foreign')
+                findings.push(finding('agents', id, 'warn', 'a directory fx did not create is in the way', {
+                    required: true,
+                    fix,
+                }));
+            else
+                findings.push(finding('agents', id, 'warn', state, {
+                    fix,
+                    required: true,
+                    actions: [repairAction(deps)],
+                }));
+        }
+    }
+    if (findings.length === 0)
+        findings.push(finding('agents', 'none', 'ok', 'no coding agent enabled on this machine'));
+    return findings;
+}
+//# sourceMappingURL=agents.js.map

package/dist/application/doctor/agents.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agents.js","sourceRoot":"","sources":["../../../src/application/doctor/agents.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAClF,qDAAqD;AAErD,OAAO,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAC;AACjD,OAAO,EAAE,SAAS,EAAE,MAAM,kBAAkB,CAAC;AAG7C,OAAO,EAAE,gBAAgB,EAAE,MAAM,0BAA0B,CAAC;AAE5D,OAAO,EAAE,OAAO,EAAgB,MAAM,YAAY,CAAC;AAEnD,MAAM,CAAC,KAAK,UAAU,WAAW,CAAC,IAAmB,EAAE,MAAiB;IACtE,MAAM,IAAI,GAAG,MAAM,IAAI,SAAS,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC;IAC3D,MAAM,QAAQ,GAAc,EAAE,CAAC;IAC/B,MAAM,GAAG,GAAG,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,QAAQ,CAAC,CAAC;IAC/D,KAAK,MAAM,GAAG,IAAI,IAAI,EAAE,CAAC;QACvB,KAAK,MAAM,CAAC,KAAK,EAAE,KAAK,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;YACxD,MAAM,EAAE,GAAG,GAAG,KAAK,IAAI,GAAG,CAAC,IAAI,EAAE,CAAC;YAClC,IAAI,KAAK,KAAK,WAAW;gBAAE,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,IAAI,EAAE,WAAW,CAAC,CAAC,CAAC;iBAC9E,IAAI,KAAK,KAAK,SAAS;gBAC1B,QAAQ,CAAC,IAAI,CACX,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,6CAA6C,EAAE;oBAC3E,QAAQ,EAAE,IAAI;oBACd,GAAG;iBACJ,CAAC,CACH,CAAC;;gBAEF,QAAQ,CAAC,IAAI,CACX,OAAO,CAAC,QAAQ,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE;oBACnC,GAAG;oBACH,QAAQ,EAAE,IAAI;oBACd,OAAO,EAAE,CAAC,YAAY,CAAC,IAAI,CAAC,CAAC;iBAC9B,CAAC,CACH,CAAC;QACN,CAAC;IACH,CAAC;IACD,IAAI,QAAQ,CAAC,MAAM,KAAK,CAAC;QACvB,QAAQ,CAAC,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,MAAM,EAAE,IAAI,EAAE,yCAAyC,CAAC,CAAC,CAAC;IAC5F,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/dist/application/doctor/index.js

@@ -0,0 +1,147 @@
+// Repairs independently, retaining each attempt, then reports fresh evidence from every check.
+import { asDevkitError, toEnvelope } from '../../domain/errors.js';
+import { report } from '../../domain/report.js';
+import { DeriveDocs } from '../docs/derive.js';
+import { handoffOf, setupActions } from '../init/setup.js';
+import { Login } from '../login/run.js';
+import { validateSetupSelection } from '../login/selection.js';
+import { findingCheck, workspacePreparation } from '../preparation.js';
+import { assertWritable } from '../safety/posture.js';
+import { SkillStage } from '../skill/stage.js';
+import { Tally } from '../tally.js';
+import { workspaceToolScope } from '../tool/scope.js';
+import { checkAgents } from './agents.js';
+import { checkInstallations } from './installations.js';
+import { checkLogin } from './login.js';
+import { checkManifest } from './manifest.js';
+import { checkRepos } from './repos.js';
+import { checkRoot } from './root.js';
+import { checkSelf } from './self.js';
+import { checkTools } from './tools.js';
+import { GROUPS, } from './types.js';
+export class Doctor {
+    deps;
+    doctor;
+    constructor(deps, doctor) {
+        this.deps = deps;
+        this.doctor = doctor;
+    }
+    async execute(input) {
+        validateSetupSelection(this.deps.ctx, input, this.deps.commandShell);
+        const toolScope = workspaceToolScope(this.deps.ctx, input, this.deps.commandShell);
+        const repairs = input.fix ? await this.fix({ ...input, tools: toolScope.configuredNames }) : [];
+        const groups = await Tally.during(this.deps.activity, 'checks', (checks) => this.check(input, toolScope, checks));
+        return this.summarize(input, toolScope, groups.flat(), repairs);
+    }
+    // One unit per group, except the two that run a companion per tool and per step.
+    check(input, toolScope, checks) {
+        const group = (name, check) => checks.plan(1).unit(name, check);
+        return Promise.all([
+            toolScope.problems,
+            group('repos', () => checkRepos(this.deps)),
+            group('root', () => checkRoot(this.deps, { hosts: this.doctor.skills.hosts, login: this.doctor.login })),
+            group('installations', () => checkInstallations(this.doctor.inventory, input.tools)),
+            checkTools(this.deps, { ...toolScope, trust: this.doctor.login.trust }, checks),
+            checkLogin(this.deps, this.doctor.login, {
+                tools: toolScope.configuredNames,
+                requiredTools: toolScope.required,
+                envs: input.envs,
+                dryRun: input.dryRun,
+            }, checks),
+            group('agents', () => checkAgents(this.deps, this.doctor.skills)),
+            group('manifest', () => checkManifest(this.deps, this.doctor.login, this.doctor.bundledTools, this.doctor.updates)),
+            group('self', () => checkSelf(this.doctor.updates)),
+            ...(this.doctor.extensions ?? []).map((extension) => group(extension.group, () => extension.check())),
+        ]);
+    }
+    async summarize(input, toolScope, findings, repairs) {
+        const groupOrder = [
+            ...GROUPS,
+            ...(this.doctor.extensions ?? []).map((extension) => extension.group),
+        ];
+        const diagnostic = report(groupOrder, findings);
+        const plan = await new Login(this.deps, this.doctor.login).plan({
+            tools: toolScope.configuredNames,
+            envs: input.envs,
+        });
+        const checks = diagnostic.findings.map((item) => this.preparationCheck(item, plan, toolScope));
+        return {
+            findings: diagnostic.findings,
+            summary: diagnostic.summary,
+            coverage: diagnostic.complete ? 'complete' : 'incomplete',
+            preparation: workspacePreparation(this.deps, groupOrder, checks, input.dryRun, {
+                tools: toolScope.configuredNames,
+                ...(input.envs ? { environments: input.envs } : {}),
+            }, {
+                id: 'recheck-preparation',
+                description: 'Recheck the same workspace and selected tools after the prerequisites change',
+                argv: [
+                    'fx',
+                    'doctor',
+                    '--workspace',
+                    this.deps.ctx.name,
+                    ...(input.tools ? input.tools.flatMap((tool) => ['--tool', tool]) : []),
+                    ...(input.envs ? input.envs.flatMap((env) => ['--env', env]) : []),
+                    ...(input.fix ? ['--fix'] : []),
+                ],
+                cwd: this.deps.ctx.root,
+                actor: 'agent',
+                requires_approval: input.dryRun,
+            }),
+            repairs,
+        };
+    }
+    // A setup step that did not pass offers the action its own handoff describes.
+    preparationCheck(item, plan, toolScope) {
+        const step = item.group === 'login' ? plan.steps.find((step) => step.id === item.id) : undefined;
+        const check = findingCheck(item, step ? toolScope.required.has(step.tool) : item.required);
+        if (step === undefined || item.level === 'ok' || item.actions)
+            return check;
+        const handoff = handoffOf(item, step);
+        return {
+            ...check,
+            actions: setupActions(this.deps, step, this.doctor.login.home, { handoff }),
+        };
+    }
+    async fix(input) {
+        if (!input.dryRun)
+            assertWritable(input.posture, 'doctor --fix');
+        const repairs = [];
+        const attempt = async (group, run) => {
+            try {
+                await run();
+                repairs.push({ group, status: input.dryRun ? 'planned' : 'completed' });
+            }
+            catch (err) {
+                const failure = asDevkitError(err);
+                if (failure.code === 'READONLY_BLOCKED')
+                    throw failure;
+                repairs.push({ group, status: 'failed', failure: toEnvelope(failure).error });
+            }
+        };
+        for (const extension of this.doctor.extensions ?? []) {
+            if (extension.fix)
+                await attempt(extension.group, () => extension.fix(input));
+        }
+        await attempt('agents', () => new SkillStage(this.deps, this.doctor.skills).execute({
+            dryRun: input.dryRun,
+            posture: input.posture,
+        }));
+        await attempt('manifest', () => new DeriveDocs(this.deps, this.doctor.login).execute({
+            check: false,
+            dryRun: input.dryRun,
+            posture: input.posture,
+        }));
+        await attempt('login', () => new Login(this.deps, this.doctor.login).execute({
+            mode: 'prepare',
+            tools: input.tools,
+            envs: input.envs,
+            skipManual: true,
+            dryRun: input.dryRun,
+            noInput: input.noInput,
+            posture: input.posture,
+        }));
+        return repairs;
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/application/doctor/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/application/doctor/index.ts"],"names":[],"mappings":"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"}

package/dist/application/doctor/installations.js

@@ -0,0 +1,29 @@
+// Removed manifest entries remain visible through personal installation evidence.
+import { asDevkitError } from '../../domain/errors.js';
+import { finding } from './types.js';
+export async function checkInstallations(inventory, names) {
+    let rows;
+    try {
+        rows = (await inventory?.execute()) ?? [];
+    }
+    catch (error) {
+        const failure = asDevkitError(error);
+        return [
+            finding('tools', 'installation-history', 'warn', failure.message, {
+                coverage: 'incomplete',
+                fix: 'fx tool history',
+                evidence: { code: failure.code },
+            }),
+        ];
+    }
+    return rows
+        .filter((row) => (names === undefined || names.includes(row.name)) &&
+        ['unused', 'unknown', 'unverified', 'changed'].includes(row.state))
+        .map((row) => finding('tools', `installation:${row.via}:${row.spec}`, 'warn', row.uninstall_hint ??
+        `${row.name}: installation evidence is ${row.state}; review history before removing the package.`, {
+        coverage: row.state === 'unused' ? 'checked' : 'incomplete',
+        fix: 'fx tool inventory',
+        evidence: { installation: row },
+    }));
+}
+//# sourceMappingURL=installations.js.map

package/dist/application/doctor/installations.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"installations.js","sourceRoot":"","sources":["../../../src/application/doctor/installations.ts"],"names":[],"mappings":"AAAA,kFAAkF;AAElF,OAAO,EAAE,aAAa,EAAE,MAAM,wBAAwB,CAAC;AAGvD,OAAO,EAAE,OAAO,EAAgB,MAAM,YAAY,CAAC;AAEnD,MAAM,CAAC,KAAK,UAAU,kBAAkB,CACtC,SAAoC,EACpC,KAAyB;IAEzB,IAAI,IAAI,CAAC;IACT,IAAI,CAAC;QACH,IAAI,GAAG,CAAC,MAAM,SAAS,EAAE,OAAO,EAAE,CAAC,IAAI,EAAE,CAAC;IAC5C,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,aAAa,CAAC,KAAK,CAAC,CAAC;QACrC,OAAO;YACL,OAAO,CAAC,OAAO,EAAE,sBAAsB,EAAE,MAAM,EAAE,OAAO,CAAC,OAAO,EAAE;gBAChE,QAAQ,EAAE,YAAY;gBACtB,GAAG,EAAE,iBAAiB;gBACtB,QAAQ,EAAE,EAAE,IAAI,EAAE,OAAO,CAAC,IAAI,EAAE;aACjC,CAAC;SACH,CAAC;IACJ,CAAC;IACD,OAAO,IAAI;SACR,MAAM,CACL,CAAC,GAAG,EAAE,EAAE,CACN,CAAC,KAAK,KAAK,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACjD,CAAC,QAAQ,EAAE,SAAS,EAAE,YAAY,EAAE,SAAS,CAAC,CAAC,QAAQ,CAAC,GAAG,CAAC,KAAK,CAAC,CACrE;SACA,GAAG,CAAC,CAAC,GAAG,EAAE,EAAE,CACX,OAAO,CACL,OAAO,EACP,gBAAgB,GAAG,CAAC,GAAG,IAAI,GAAG,CAAC,IAAI,EAAE,EACrC,MAAM,EACN,GAAG,CAAC,cAAc;QAChB,GAAG,GAAG,CAAC,IAAI,8BAA8B,GAAG,CAAC,KAAK,+CAA+C,EACnG;QACE,QAAQ,EAAE,GAAG,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,YAAY;QAC3D,GAAG,EAAE,mBAAmB;QACxB,QAAQ,EAAE,EAAE,YAAY,EAAE,GAAG,EAAE;KAChC,CACF,CACF,CAAC;AACN,CAAC"}