@akanjs/cli 2.4.0-rc.9 → 2.4.1-rc.0

package/index-qhtr07v8.js

@@ -0,0 +1,1072 @@
+// @bun
+import {
+  WorkflowRunner
+} from "./index-45aj5ry0.js";
+import {
+  ScalarScript
+} from "./index-y3hdhy4p.js";
+import {
+  PrimitiveScript
+} from "./index-73pr2cmy.js";
+import {
+  RepairRunner
+} from "./index-85msc0wg.js";
+import {
+  isPlaceholderAppId
+} from "./index-1xdrsbry.js";
+import {
+  AkanContextAnalyzer,
+  akanMcpInstallConfigPaths,
+  akanMcpInstallTargets,
+  codexMcpConfigPath,
+  createAkanCodexMcpServerBlock,
+  createAkanMcpServer,
+  renderDoctorText,
+  resourceList,
+  upsertCodexMcpServerBlock
+} from "./index-8rc0bm04.js";
+import {
+  getMobileTargets
+} from "./index-76rn3g2c.js";
+import {
+  ModuleScript
+} from "./index-8pkbzj26.js";
+import {
+  Prompter
+} from "./index-qaq13qk3.js";
+import {
+  buildAkanModuleContextIndex,
+  createWorkflowBaselineSummary,
+  createWorkflowStepRegistry,
+  jsonText,
+  toolingRolloutGate
+} from "./index-h6ca6qg0.js";
+import {
+  CommandContainer,
+  runner,
+  script
+} from "./index-hdqztm58.js";
+import {
+  AppExecutor
+} from "./index-a6sbyy0b.js";
+
+// pkgs/@akanjs/cli/context/context.script.ts
+import { Logger } from "akanjs/common";
+
+// pkgs/@akanjs/devkit/akanMcpContract.ts
+import path from "path";
+var emptySchema = { type: "object", properties: {} };
+var stringProperty = { type: "string" };
+var booleanProperty = { type: "boolean" };
+var objectProperty = { type: "object", additionalProperties: true };
+var stringArrayProperty = { type: "array", items: stringProperty };
+var inspectAkanContextRequestTypes = [
+  "workspaceOverview",
+  "moduleContext",
+  "fieldInsertionContext",
+  "workflowDiagnostics",
+  "escape"
+];
+var inspectAkanContextRequestTypeProperty = { type: "string", enum: inspectAkanContextRequestTypes };
+var inspectAkanContextRequestBranches = [
+  {
+    type: "object",
+    properties: { type: { const: "workspaceOverview" } },
+    required: ["type"]
+  },
+  {
+    type: "object",
+    properties: { type: { const: "moduleContext" }, app: stringProperty, module: stringProperty },
+    required: ["type", "app", "module"]
+  },
+  {
+    type: "object",
+    properties: {
+      type: { const: "fieldInsertionContext" },
+      app: stringProperty,
+      module: stringProperty,
+      field: stringProperty,
+      fieldType: stringProperty
+    },
+    required: ["type", "app", "module", "field", "fieldType"]
+  },
+  {
+    type: "object",
+    properties: { type: { const: "workflowDiagnostics" }, runIdOrPlan: stringProperty },
+    required: ["type", "runIdOrPlan"]
+  },
+  {
+    type: "object",
+    properties: { type: { const: "escape" }, reason: stringProperty, nextStep: stringProperty },
+    required: ["type", "reason"]
+  }
+];
+var inspectAkanContextInputSchema = {
+  type: "object",
+  properties: {
+    question: {
+      ...stringProperty,
+      description: "The user-facing question the agent is trying to answer before reading source bodies."
+    },
+    draft: {
+      type: "object",
+      properties: {
+        reason: stringProperty,
+        type: inspectAkanContextRequestTypeProperty
+      },
+      required: ["reason", "type"]
+    },
+    review: {
+      ...stringProperty,
+      description: "A short self-review explaining why this minimal request is sufficient."
+    },
+    request: {
+      type: "object",
+      properties: {
+        type: inspectAkanContextRequestTypeProperty,
+        app: stringProperty,
+        module: stringProperty,
+        field: stringProperty,
+        fieldType: stringProperty,
+        runIdOrPlan: stringProperty,
+        reason: stringProperty,
+        nextStep: stringProperty
+      },
+      required: ["type"],
+      oneOf: inspectAkanContextRequestBranches
+    }
+  },
+  required: ["question", "draft", "review", "request"]
+};
+var isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var slugPart = (value) => typeof value === "string" ? value.trim().replace(/[^a-zA-Z0-9]+/g, "-").replace(/^-+|-+$/g, "").toLowerCase() : "";
+var optionalString = (args, key) => {
+  const value = args[key];
+  return typeof value === "string" && value ? value : undefined;
+};
+var nestedStringArg = (args, key) => {
+  const value = args[key];
+  if (typeof value !== "string" || !value)
+    throw new Error(`MCP tool argument "${key}" is required.`);
+  return value;
+};
+var isInspectAkanContextRequestType = (value) => typeof value === "string" && inspectAkanContextRequestTypes.includes(value);
+var parseJsonOutput = (output) => JSON.parse(output);
+var workspacePath = (workspace, filePath) => path.isAbsolute(filePath) ? filePath : path.join(workspace.workspaceRoot, filePath);
+var defaultWorkflowPlanPath = (workflow, inputs) => {
+  const slug = [
+    slugPart(workflow),
+    slugPart(inputs.app),
+    slugPart(inputs.module),
+    slugPart(inputs.field),
+    slugPart(inputs.scalar),
+    slugPart(inputs.surface),
+    slugPart(inputs.mutation),
+    slugPart(inputs.slice)
+  ].filter(Boolean).join("-");
+  return `.akan/workflows/plans/${slug || "workflow-plan"}.json`;
+};
+var applyFirstPolicy = {
+  mode: "apply-first",
+  directSourceEdits: "fallback-only",
+  applyRequiredWhen: ["plan_workflow returns planPath", "plan_workflow returns next.tool=apply_workflow"],
+  approvalMeaning: "requiresApproval is an agent/user review signal before apply_workflow mutates files; it is not a separate MCP permission gate.",
+  validationRequiredAfterApply: ["validationTarget", "applyReportPath"],
+  fallbackAllowedWhen: [
+    "list_workflows and explain_workflow show no matching workflow",
+    "apply_workflow reports unsupported/no-op/failed diagnostics that require manual action",
+    "recommendations include manual-action follow-up after workflow apply and repairs"
+  ],
+  baselineDiagnosticsPolicy: "Do not fix unrelated baselineDiagnostics unless the user asks."
+};
+var stringArg = (args, key) => {
+  const value = args[key];
+  if (typeof value !== "string" || !value)
+    throw new Error(`MCP tool argument "${key}" is required.`);
+  return value;
+};
+var workflowInputsArg = (args) => {
+  const value = args.inputs;
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    return {};
+  return value;
+};
+var inspectAkanContextPropsArg = (args) => {
+  const question = stringArg(args, "question");
+  const review = stringArg(args, "review");
+  if (!isRecord(args.draft))
+    throw new Error('MCP tool argument "draft" is required.');
+  if (!isRecord(args.request))
+    throw new Error('MCP tool argument "request" is required.');
+  if (!isInspectAkanContextRequestType(args.draft.type)) {
+    throw new Error('MCP tool argument "draft.type" must be a supported inspect_akan_context request type.');
+  }
+  if (!isInspectAkanContextRequestType(args.request.type)) {
+    throw new Error('MCP tool argument "request.type" must be a supported inspect_akan_context request type.');
+  }
+  const draft = { reason: nestedStringArg(args.draft, "reason"), type: args.draft.type };
+  const request = args.request;
+  if (request.type === "workspaceOverview")
+    return { question, draft, review, request: { type: request.type } };
+  if (request.type === "moduleContext")
+    return {
+      question,
+      draft,
+      review,
+      request: {
+        type: request.type,
+        app: nestedStringArg(request, "app"),
+        module: nestedStringArg(request, "module")
+      }
+    };
+  if (request.type === "fieldInsertionContext")
+    return {
+      question,
+      draft,
+      review,
+      request: {
+        type: request.type,
+        app: nestedStringArg(request, "app"),
+        module: nestedStringArg(request, "module"),
+        field: nestedStringArg(request, "field"),
+        fieldType: nestedStringArg(request, "fieldType")
+      }
+    };
+  if (request.type === "workflowDiagnostics")
+    return {
+      question,
+      draft,
+      review,
+      request: { type: request.type, runIdOrPlan: nestedStringArg(request, "runIdOrPlan") }
+    };
+  return {
+    question,
+    draft,
+    review,
+    request: {
+      type: "escape",
+      reason: nestedStringArg(request, "reason"),
+      nextStep: optionalString(request, "nextStep")
+    }
+  };
+};
+var inspectDiagnostic = (severity, code, message) => ({ severity, code, message });
+var moduleEvidence = (module) => ({
+  kind: "module",
+  target: `${module.sysName}:${module.name}`,
+  path: module.path,
+  summary: `${module.kind} module at ${module.path} with ${module.files.length} source file(s).`
+});
+var moduleCandidate = (module) => ({
+  app: module.sysName,
+  sysType: module.sysType,
+  module: module.name,
+  kind: module.kind,
+  path: module.path,
+  files: module.files
+});
+var readonlyMcpTools = [
+  {
+    name: "inspect_akan_context",
+    description: "Read-only typed context inspection. Use question -> draft -> review -> request before source body reads; choose fieldInsertionContext for add-field evidence and escape when source body or outside evidence is required.",
+    inputSchema: inspectAkanContextInputSchema
+  },
+  {
+    name: "get_workspace_summary",
+    description: "Legacy broad workspace summary. Prefer inspect_akan_context.workspaceOverview for typed source-body-free evidence.",
+    inputSchema: emptySchema
+  },
+  {
+    name: "list_apps",
+    description: "List Akan apps from the workspace context without reading source bodies.",
+    inputSchema: emptySchema
+  },
+  {
+    name: "list_modules",
+    description: "List Akan modules across apps and libs; use inspect_akan_context.moduleContext for typed evidence.",
+    inputSchema: emptySchema
+  },
+  {
+    name: "get_module_context",
+    description: "Legacy broad module context. Pass app in monorepos; prefer inspect_akan_context.moduleContext or fieldInsertionContext for typed add-field evidence.",
+    inputSchema: { type: "object", properties: { app: stringProperty, module: stringProperty }, required: ["module"] }
+  },
+  {
+    name: "get_guideline",
+    description: "Return an Akan agent guideline resource by name.",
+    inputSchema: { type: "object", properties: { name: stringProperty }, required: ["name"] }
+  },
+  {
+    name: "explain_command",
+    description: "Explain one Akan CLI command and its agent-facing workflow policy.",
+    inputSchema: { type: "object", properties: { command: stringProperty }, required: ["command"] }
+  },
+  {
+    name: "doctor_workspace",
+    description: "Report workspace diagnostics, optionally split into baseline and workflow scopes.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        strict: booleanProperty,
+        runIdOrPlan: stringProperty,
+        changedFiles: stringArrayProperty,
+        includeBaselineDetails: booleanProperty
+      }
+    }
+  },
+  {
+    name: "get_validation_contract",
+    description: "Return validation, artifact chain, and apply-first fallback policy.",
+    inputSchema: emptySchema
+  }
+];
+var planMcpTools = [
+  {
+    name: "list_workflows",
+    description: "List available read-only workflow specs before creating a plan.",
+    inputSchema: emptySchema
+  },
+  {
+    name: "explain_workflow",
+    description: "Explain one workflow's inputs, predicted changes, validation, and completion criteria.",
+    inputSchema: { type: "object", properties: { workflow: stringProperty }, required: ["workflow"] }
+  },
+  {
+    name: "plan_workflow",
+    description: "Create a read-only workflow plan after context inspection and return planPath plus next.tool=apply_workflow.",
+    inputSchema: {
+      type: "object",
+      properties: { workflow: stringProperty, inputs: objectProperty, out: stringProperty },
+      required: ["workflow"]
+    }
+  }
+];
+var applyMcpTools = [
+  {
+    name: "apply_workflow",
+    description: "Apply a stored workflow plan before direct edits and return validationTarget for run_validation.",
+    inputSchema: {
+      type: "object",
+      properties: { planPath: stringProperty, dryRun: booleanProperty },
+      required: ["planPath"]
+    }
+  },
+  {
+    name: "run_validation",
+    description: "Validate a plan, apply report, validationTarget, or run artifact.",
+    inputSchema: {
+      type: "object",
+      properties: { runIdOrPlan: stringProperty, includeBaselineDetails: booleanProperty },
+      required: ["runIdOrPlan"]
+    }
+  },
+  {
+    name: "repair_generated",
+    description: "Refresh generated Akan files before direct generated-file edits.",
+    inputSchema: { type: "object", properties: { app: stringProperty }, required: ["app"] }
+  },
+  {
+    name: "repair_imports",
+    description: "Run the import repair path before manual import edits.",
+    inputSchema: { type: "object", properties: { target: stringProperty }, required: ["target"] }
+  },
+  {
+    name: "repair_module_shape",
+    description: "Report module-shape repair actions before direct module file fixes.",
+    inputSchema: {
+      type: "object",
+      properties: { app: stringProperty, module: stringProperty },
+      required: ["app", "module"]
+    }
+  }
+];
+var listAkanMcpTools = (mode = "readonly") => {
+  if (mode === "readonly")
+    return readonlyMcpTools;
+  if (mode === "plan")
+    return [...readonlyMcpTools, ...planMcpTools];
+  return [...readonlyMcpTools, ...planMcpTools, ...applyMcpTools];
+};
+var createAkanValidationContract = (listTools = listAkanMcpTools) => ({
+  schemaVersion: 1,
+  reports: ["WorkflowPlan", "WorkflowApplyReport", "WorkflowValidationRunReport", "RepairReport"],
+  modes: {
+    readonly: listTools("readonly").map((tool) => tool.name),
+    plan: listTools("plan").map((tool) => tool.name),
+    apply: listTools("apply").map((tool) => tool.name)
+  },
+  validationCommands: [
+    "akan workflow validate <run-id-or-plan> --format json",
+    "akan workflow report <run-id> --format json",
+    "akan doctor --strict --format json"
+  ],
+  validationFailureScopes: ["workspace-config", "environment", "source-change", "unknown"],
+  artifactChainFields: ["planPath", "applyReportPath", "repairReportPath", "runId", "validationTarget", "next"],
+  diagnosticScopes: ["baseline", "workflow", "unknown"],
+  validationStatuses: {
+    sourceStatus: ["passed", "failed", "unknown"],
+    workspaceStatus: ["passed", "failed", "unknown"],
+    validationCommandsStatus: ["passed", "failed", "unknown"],
+    baselineStatus: ["passed", "failed", "unknown"],
+    overallStatus: [
+      "passed",
+      "failed",
+      "passed-with-baseline-blockers",
+      "blocked-by-workspace-config",
+      "blocked-by-environment"
+    ],
+    baselineSummary: "Default MCP validation output summarizes baseline diagnostics; pass includeBaselineDetails=true for full baselineDiagnostics.",
+    knownBlockers: "Repeated workspace-config/environment failures are summarized before command output."
+  },
+  moduleContextInputs: {
+    module: "required",
+    app: "required"
+  },
+  generatedFreshnessStatuses: ["fresh", "stale", "missing", "unknown"],
+  toolingRolloutGate,
+  directEditFallbackPolicy: applyFirstPolicy,
+  applyReportFields: [
+    "summary",
+    "appliedCommands",
+    "recommendedValidationCommands",
+    "commands",
+    "recommendations",
+    "validationTarget"
+  ],
+  repairCommands: [
+    "akan repair generated --app <app-or-lib> --format json",
+    "akan repair format --target <app-or-lib-or-pkg> --format json",
+    "akan repair imports --target <app-or-lib-or-pkg> --format json",
+    "akan repair dictionary --app <app-or-lib> --module <module> --format json",
+    "akan repair module-shape --app <app-or-lib> --module <module> --format json"
+  ]
+});
+var inspectAkanContext = async (workspace, args) => {
+  const props = inspectAkanContextPropsArg(args);
+  const diagnostics = [];
+  if (props.draft.type !== props.request.type) {
+    diagnostics.push(inspectDiagnostic("warning", "inspect-draft-request-mismatch", `Draft chose ${props.draft.type}, but request uses ${props.request.type}.`));
+  }
+  const baseResult = (type, evidence, next, data) => ({
+    schemaVersion: 1,
+    type,
+    question: props.question,
+    diagnostics,
+    evidence,
+    next,
+    ...data ? { data } : {}
+  });
+  if (props.request.type === "escape") {
+    return baseResult("escape", [{ kind: "escape", summary: props.request.reason }], {
+      action: "escape",
+      reason: props.request.reason,
+      ...props.request.nextStep ? { args: { nextStep: props.request.nextStep } } : {}
+    }, { reason: props.request.reason, nextStep: props.request.nextStep ?? null });
+  }
+  if (props.request.type === "workflowDiagnostics") {
+    const doctor = await AkanContextAnalyzer.doctor(workspace, {
+      strict: true,
+      runIdOrPlan: workspacePath(workspace, props.request.runIdOrPlan)
+    });
+    const baselineSummary = createWorkflowBaselineSummary((doctor.baselineDiagnostics ?? []).map((diagnostic) => ({
+      severity: diagnostic.severity,
+      code: diagnostic.code,
+      message: diagnostic.message,
+      scope: diagnostic.scope,
+      context: diagnostic.context
+    })), { detailsIncluded: false });
+    diagnostics.push(...(doctor.workflowDiagnostics ?? doctor.diagnostics).map((diagnostic) => ({
+      severity: diagnostic.severity,
+      code: diagnostic.code,
+      message: diagnostic.message,
+      scope: diagnostic.scope,
+      context: {
+        ...diagnostic.context,
+        ...diagnostic.path ? { paths: [diagnostic.path] } : {}
+      }
+    })));
+    return baseResult("workflowDiagnostics", [
+      {
+        kind: "workflow",
+        target: props.request.runIdOrPlan,
+        summary: `Workflow diagnostics status is ${doctor.status}.`
+      }
+    ], {
+      action: doctor.status === "passed" ? "answer" : "validate",
+      reason: doctor.status === "passed" ? "No strict workspace diagnostics were found for the workflow context." : "Review diagnostics before applying or manually editing source files."
+    }, {
+      status: doctor.status,
+      baselineSummary,
+      baselineDiagnostics: 0,
+      workflowDiagnostics: doctor.workflowDiagnostics?.length ?? 0
+    });
+  }
+  const context = await AkanContextAnalyzer.analyze(workspace, {
+    app: props.request.type === "moduleContext" || props.request.type === "fieldInsertionContext" ? props.request.app : null,
+    module: props.request.type === "moduleContext" || props.request.type === "fieldInsertionContext" ? props.request.module : null,
+    includeAbstractContent: false
+  });
+  if (props.request.type === "workspaceOverview") {
+    return baseResult("workspaceOverview", [
+      {
+        kind: "workspace",
+        summary: `${context.repoName} has ${context.apps.length} app(s), ${context.libs.length} lib(s), and ${context.pkgs.length} package(s).`
+      }
+    ], {
+      action: "inspect",
+      reason: "Choose moduleContext or fieldInsertionContext for module-scoped evidence before planning a workflow.",
+      tool: "inspect_akan_context"
+    }, {
+      repoName: context.repoName,
+      apps: context.apps.map((app) => ({ name: app.name, path: app.path, modules: app.modules.length })),
+      libs: context.libs.map((lib) => ({ name: lib.name, path: lib.path, modules: lib.modules.length })),
+      pkgs: context.pkgs.map((pkg) => ({ name: pkg.name, path: pkg.path, version: pkg.version ?? null })),
+      generatedFiles: context.generatedFiles,
+      validationCommands: context.validationCommands
+    });
+  }
+  const modules = AkanContextAnalyzer.findModules(context, props.request.module, {
+    app: props.request.app ?? null
+  });
+  if (modules.length === 0) {
+    diagnostics.push(inspectDiagnostic("error", "inspect-module-not-found", `No module matched ${props.request.app ? `${props.request.app}:` : ""}${props.request.module}.`));
+    return baseResult(props.request.type, [], {
+      action: "escape",
+      reason: "The requested module was not found in the workspace index; inspect workspace files or clarify the target."
+    }, { candidates: [] });
+  }
+  if (!props.request.app && modules.length > 1) {
+    diagnostics.push(inspectDiagnostic("error", "inspect-module-ambiguous", `Multiple modules match "${props.request.module}". Re-run with app to disambiguate.`));
+    return baseResult(props.request.type, modules.map(moduleEvidence), {
+      action: "clarify",
+      reason: "Multiple modules have the same name; choose an app before planning a workflow."
+    }, { candidates: modules.map(moduleCandidate) });
+  }
+  const module = modules[0];
+  if (props.request.type === "moduleContext") {
+    return baseResult("moduleContext", [moduleEvidence(module)], {
+      action: "inspect",
+      reason: "Use fieldInsertionContext when preparing add-field or escape when source body details are required.",
+      tool: "inspect_akan_context"
+    }, { module: moduleCandidate(module) });
+  }
+  if (module.kind !== "domain") {
+    diagnostics.push(inspectDiagnostic("error", "field-insertion-unsupported-module-kind", `fieldInsertionContext currently targets domain modules; ${module.sysName}:${module.name} is ${module.kind}.`));
+  }
+  const moduleIndex = await buildAkanModuleContextIndex(workspace, module, { field: props.request.field });
+  diagnostics.push(...moduleIndex.diagnostics);
+  return baseResult("fieldInsertionContext", [
+    moduleEvidence(module),
+    {
+      kind: "field-insertion",
+      target: `${module.sysName}:${module.name}.${props.request.field}`,
+      path: module.path,
+      summary: "M2 returns source-body-free AST index evidence for constant fields, dictionary model labels, and light projection fields."
+    }
+  ], module.kind === "domain" ? {
+    action: "plan_workflow",
+    reason: "The module target is unambiguous; create an add-field workflow plan before source edits.",
+    tool: "plan_workflow",
+    args: {
+      workflow: "add-field",
+      inputs: {
+        app: module.sysName,
+        module: module.name,
+        field: props.request.field,
+        type: props.request.fieldType
+      }
+    }
+  } : {
+    action: "escape",
+    reason: "This module kind is not a supported add-field target in the P1 context contract."
+  }, {
+    target: {
+      app: module.sysName,
+      module: module.name,
+      field: props.request.field,
+      fieldType: props.request.fieldType
+    },
+    files: moduleIndex.files,
+    moduleIndex
+  });
+};
+
+// pkgs/@akanjs/cli/context/context.workflowRegistry.ts
+var createCliWorkflowStepRegistry = (workspace) => createWorkflowStepRegistry({
+  workspace,
+  createModule: (sys, module) => CommandContainer.get(ModuleScript).createModuleTemplate(sys, module),
+  createScalar: (sys, scalar) => CommandContainer.get(ScalarScript).createScalar(sys, scalar),
+  createUi: (input) => CommandContainer.get(PrimitiveScript).createUi(workspace, input),
+  addField: (input) => CommandContainer.get(PrimitiveScript).addField(workspace, input),
+  addEnumField: (input) => CommandContainer.get(PrimitiveScript).addEnumField(workspace, input),
+  addMutation: (input) => CommandContainer.get(PrimitiveScript).addMutation(workspace, input),
+  addSlice: (input) => CommandContainer.get(PrimitiveScript).addSlice(workspace, input)
+});
+
+// pkgs/@akanjs/cli/context/context.runner.ts
+var workflowDiagnosticFromContext = (diagnostic) => ({
+  severity: diagnostic.severity,
+  code: diagnostic.code,
+  message: diagnostic.message,
+  scope: diagnostic.scope,
+  context: diagnostic.context
+});
+var compactDoctorWorkspaceResult = (result, includeBaselineDetails) => {
+  const baselineDiagnostics = result.baselineDiagnostics ?? [];
+  if (baselineDiagnostics.length === 0) {
+    return {
+      ...result,
+      baselineSummary: createWorkflowBaselineSummary([], { detailsIncluded: includeBaselineDetails })
+    };
+  }
+  const baselineSummary = createWorkflowBaselineSummary(baselineDiagnostics.map(workflowDiagnosticFromContext), {
+    detailsIncluded: includeBaselineDetails
+  });
+  return {
+    ...result,
+    baselineSummary,
+    diagnostics: includeBaselineDetails ? result.diagnostics : result.diagnostics.filter((diagnostic) => diagnostic.scope !== "baseline"),
+    baselineDiagnostics: includeBaselineDetails ? baselineDiagnostics : []
+  };
+};
+
+class ContextRunner extends runner("context") {
+  async getContext(workspace, {
+    format = "markdown",
+    app = null,
+    module = null
+  } = {}) {
+    const context = await AkanContextAnalyzer.analyze(workspace, {
+      app,
+      module,
+      includeAbstractContent: !!module
+    });
+    return format === "json" ? jsonText(context) : AkanContextAnalyzer.renderMarkdown(context, { module });
+  }
+  async doctor(workspace, {
+    format = "text",
+    strict = false,
+    ios = false
+  } = {}) {
+    if (ios)
+      return await this.#doctorIos(workspace, format);
+    const result = await AkanContextAnalyzer.doctor(workspace, { strict });
+    return format === "json" ? jsonText(result) : renderDoctorText(result);
+  }
+  async#doctorIos(workspace, format) {
+    const appNames = await workspace.getApps();
+    const diagnostics = [];
+    for (const appName of appNames) {
+      const app = AppExecutor.from(workspace, appName);
+      const config = await app.getConfig();
+      if (!config.hasMobileConfig)
+        continue;
+      for (const { name, config: target } of await getMobileTargets(app)) {
+        if (!isPlaceholderAppId(target.appId))
+          continue;
+        diagnostics.push({
+          severity: "warning",
+          code: "mobile-appid-placeholder",
+          path: `apps/${appName}/akan.config.ts`,
+          message: `Mobile target '${name}' uses placeholder bundle id '${target.appId}'. Apple's developer portal almost always already claims it, so signing to a physical device fails with "cannot be registered to your development team". Set a unique mobile.appId (reverse-DNS of your org).`
+        });
+      }
+    }
+    const status = diagnostics.some((diagnostic) => diagnostic.severity === "error") ? "failed" : "passed";
+    if (format === "json")
+      return jsonText({ schemaVersion: 1, kind: "ios", status, diagnostics });
+    const lines = [`Akan iOS diagnostics for ${workspace.repoName}`];
+    if (diagnostics.length === 0)
+      lines.push("  No mobile configuration issues found.");
+    else
+      for (const diagnostic of diagnostics) {
+        lines.push(`  [${diagnostic.severity}] ${diagnostic.code}: ${diagnostic.message}`);
+        lines.push(`    ${diagnostic.path}`);
+      }
+    return lines.join(`
+`);
+  }
+  async getGuidelineResource(name) {
+    return await Prompter.getInstruction(name);
+  }
+  async installMcp(workspace, target, { force = false, mode = "readonly" } = {}) {
+    if (target === "codex")
+      return await this.#installCodexMcp(workspace, { force, mode });
+    return await this.#installJsonMcp(workspace, target, { force, mode });
+  }
+  async#installJsonMcp(workspace, target, { force, mode }) {
+    const configPath = akanMcpInstallConfigPaths[target];
+    const existing = await workspace.exists(configPath) ? await workspace.readJson(configPath) : {};
+    const mcpServers = existing.mcpServers ?? {};
+    const currentAkanServer = mcpServers.akan;
+    const nextAkanServer = createAkanMcpServer(target, mode);
+    if (currentAkanServer && !force && JSON.stringify(currentAkanServer) !== JSON.stringify(nextAkanServer)) {
+      throw new Error(`${configPath} already has an "akan" MCP server. Re-run with --force to overwrite it.`);
+    }
+    const nextConfig = {
+      ...existing,
+      mcpServers: {
+        ...mcpServers,
+        akan: nextAkanServer
+      }
+    };
+    await workspace.writeFile(configPath, `${JSON.stringify(nextConfig, null, 2)}
+`);
+    return configPath;
+  }
+  async#installCodexMcp(workspace, { force, mode }) {
+    const existing = await workspace.exists(codexMcpConfigPath) ? await workspace.readFile(codexMcpConfigPath) : "";
+    const merged = upsertCodexMcpServerBlock(existing, createAkanCodexMcpServerBlock(mode), { force });
+    await workspace.writeFile(codexMcpConfigPath, merged);
+    return codexMcpConfigPath;
+  }
+  listMcpTools(mode = "readonly") {
+    return listAkanMcpTools(mode);
+  }
+  async callMcpTool(workspace, name, args = {}, { mode = "readonly" } = {}) {
+    const availableTools = this.listMcpTools(mode);
+    if (!availableTools.some((tool) => tool.name === name)) {
+      throw new Error(`MCP tool "${name}" is not available in ${mode} mode.`);
+    }
+    if (name === "inspect_akan_context")
+      return await inspectAkanContext(workspace, args);
+    if (name === "get_workspace_summary" || name === "list_apps" || name === "list_modules" || name === "get_module_context") {
+      const context = await AkanContextAnalyzer.analyze(workspace, {
+        app: args.app ?? null,
+        module: args.module ?? null,
+        includeAbstractContent: name === "get_module_context"
+      });
+      if (name === "get_workspace_summary")
+        return context;
+      if (name === "list_apps")
+        return context.apps;
+      if (name === "list_modules")
+        return AkanContextAnalyzer.findModules(context);
+      const modules = AkanContextAnalyzer.findModules(context, args.module, {
+        app: args.app ?? null
+      });
+      if (name === "get_module_context" && !args.app && modules.length > 1) {
+        return {
+          diagnostics: [
+            {
+              severity: "error",
+              code: "module-context-ambiguous",
+              message: `Multiple modules match "${args.module}". Re-run get_module_context with an app argument.`,
+              input: "app"
+            }
+          ],
+          candidates: modules.map((module) => ({
+            app: module.sysName,
+            sysType: module.sysType,
+            module: module.name,
+            path: module.path
+          }))
+        };
+      }
+      return modules;
+    }
+    if (name === "get_guideline")
+      return await Prompter.getInstruction(stringArg(args, "name"));
+    if (name === "doctor_workspace")
+      return compactDoctorWorkspaceResult(await AkanContextAnalyzer.doctor(workspace, {
+        strict: !!args.strict,
+        runIdOrPlan: typeof args.runIdOrPlan === "string" ? workspacePath(workspace, args.runIdOrPlan) : null,
+        changedFiles: Array.isArray(args.changedFiles) ? args.changedFiles.filter((file) => typeof file === "string") : []
+      }), !!args.includeBaselineDetails);
+    if (name === "explain_command")
+      return this.explainCommand(stringArg(args, "command"));
+    if (name === "get_validation_contract")
+      return createAkanValidationContract((mode2) => this.listMcpTools(mode2));
+    if (name === "list_workflows")
+      return parseJsonOutput(new WorkflowRunner().list({ format: "json" }));
+    if (name === "explain_workflow")
+      return parseJsonOutput(new WorkflowRunner().explain(stringArg(args, "workflow"), { format: "json" }));
+    if (name === "plan_workflow") {
+      const workflow = stringArg(args, "workflow");
+      const inputs = workflowInputsArg(args);
+      const planPath = typeof args.out === "string" && args.out ? args.out : defaultWorkflowPlanPath(workflow, inputs);
+      const plan = parseJsonOutput(await new WorkflowRunner().plan(workflow, inputs, {
+        format: "json",
+        out: workspacePath(workspace, planPath)
+      }));
+      return {
+        ...plan,
+        planPath,
+        approval: typeof plan === "object" && plan && "approval" in plan ? { ...plan.approval, canApplyWith: { planPath } } : undefined,
+        next: { tool: "apply_workflow", args: { planPath } },
+        policy: applyFirstPolicy
+      };
+    }
+    if (name === "apply_workflow") {
+      const report = parseJsonOutput(await new WorkflowRunner().apply(workspacePath(workspace, stringArg(args, "planPath")), {
+        format: "json",
+        dryRun: !!args.dryRun,
+        workspace,
+        registry: createCliWorkflowStepRegistry(workspace)
+      }));
+      const validationTarget = typeof report.validationTarget === "string" ? report.validationTarget : typeof report.applyReportPath === "string" ? report.applyReportPath : stringArg(args, "planPath");
+      return {
+        ...report,
+        validationTarget,
+        next: { tool: "run_validation", args: { runIdOrPlan: validationTarget } },
+        policy: applyFirstPolicy
+      };
+    }
+    if (name === "run_validation")
+      return parseJsonOutput(await new WorkflowRunner().validate(workspacePath(workspace, stringArg(args, "runIdOrPlan")), {
+        format: "json",
+        workspace,
+        includeBaselineDetails: !!args.includeBaselineDetails
+      }));
+    if (name === "repair_generated") {
+      const report = parseJsonOutput(await new RepairRunner().repair("generated", { workspace, app: stringArg(args, "app"), format: "json" }));
+      return { ...report, next: { tool: "doctor_workspace", args: { strict: true } } };
+    }
+    if (name === "repair_imports")
+      return parseJsonOutput(await new RepairRunner().repair("imports", {
+        workspace,
+        target: stringArg(args, "target"),
+        format: "json"
+      }));
+    if (name === "repair_module_shape")
+      return parseJsonOutput(await new RepairRunner().repair("module-shape", {
+        workspace,
+        app: stringArg(args, "app"),
+        module: stringArg(args, "module"),
+        format: "json"
+      }));
+    throw new Error(`Unknown tool: ${name}`);
+  }
+  async runMcp(workspace, { mode = "readonly" } = {}) {
+    const decoder = new TextDecoder;
+    let buffer = "";
+    const writeMessage = (message, framing) => {
+      const payload = JSON.stringify(message);
+      if (framing === "newline")
+        process.stdout.write(`${payload}
+`);
+      else
+        process.stdout.write(`Content-Length: ${Buffer.byteLength(payload)}\r
+\r
+${payload}`);
+    };
+    const respond = (id, result, framing) => {
+      writeMessage({ jsonrpc: "2.0", id, result }, framing);
+    };
+    const respondError = (id, code, message, framing) => {
+      writeMessage({ jsonrpc: "2.0", id, error: { code, message } }, framing);
+    };
+    const readResource = async (uri) => {
+      const context = await AkanContextAnalyzer.analyze(workspace);
+      if (uri === "akan://docs/framework" || uri === "akan://guidelines/framework")
+        return { uri, mimeType: "text/markdown", text: await Prompter.getInstruction("framework") };
+      if (uri === "akan://guidelines/modelSignal")
+        return { uri, mimeType: "text/markdown", text: await Prompter.getInstruction("modelSignal") };
+      if (uri === "akan://workspace/summary")
+        return { uri, mimeType: "application/json", text: jsonText(context, { trailingNewline: false }) };
+      if (uri === "akan://workspace/apps")
+        return { uri, mimeType: "application/json", text: jsonText(context.apps, { trailingNewline: false }) };
+      if (uri === "akan://workspace/modules")
+        return {
+          uri,
+          mimeType: "application/json",
+          text: jsonText(AkanContextAnalyzer.findModules(context), { trailingNewline: false })
+        };
+      const abstractMatch = uri.match(/^akan:\/\/workspace\/modules\/(.+)\/abstract$/);
+      if (abstractMatch) {
+        const detailed = await AkanContextAnalyzer.analyze(workspace, {
+          module: abstractMatch[1],
+          includeAbstractContent: true
+        });
+        const abstract = AkanContextAnalyzer.findModules(detailed, abstractMatch[1])[0]?.abstract;
+        return { uri, mimeType: "text/markdown", text: abstract?.content ?? "" };
+      }
+      throw new Error(`Unknown resource: ${uri}`);
+    };
+    const handle = async (request, framing) => {
+      const params = request.params ?? {};
+      if (request.method === "initialize") {
+        respond(request.id, {
+          protocolVersion: "2024-11-05",
+          capabilities: { tools: {}, resources: {} },
+          serverInfo: { name: "akan", version: process.env.AKAN_VERSION ?? "0.0.0" }
+        }, framing);
+      } else if (request.method === "tools/list") {
+        respond(request.id, {
+          tools: this.listMcpTools(mode)
+        }, framing);
+      } else if (request.method === "tools/call") {
+        const name = params.name;
+        const args = params.arguments ?? {};
+        try {
+          const result = await this.callMcpTool(workspace, name, args, { mode });
+          respond(request.id, {
+            content: [
+              {
+                type: "text",
+                text: typeof result === "string" ? result : jsonText(result, { trailingNewline: false })
+              }
+            ]
+          }, framing);
+        } catch (error) {
+          respondError(request.id, -32602, error instanceof Error ? error.message : String(error), framing);
+        }
+      } else if (request.method === "resources/list") {
+        respond(request.id, { resources: resourceList }, framing);
+      } else if (request.method === "resources/read") {
+        respond(request.id, { contents: [await readResource(params.uri)] }, framing);
+      } else if (!request.method.endsWith("/initialized")) {
+        respondError(request.id, -32601, `Unknown method: ${request.method}`, framing);
+      }
+    };
+    const parseContentLengthMessage = async () => {
+      const headerEnd = buffer.indexOf(`\r
+\r
+`);
+      if (headerEnd < 0)
+        return false;
+      const header = buffer.slice(0, headerEnd);
+      const match = /Content-Length:\s*(\d+)/i.exec(header);
+      if (!match) {
+        buffer = buffer.slice(headerEnd + 4);
+        return true;
+      }
+      const length = Number(match[1]);
+      const bodyStart = headerEnd + 4;
+      const bodyEnd = bodyStart + length;
+      if (buffer.length < bodyEnd)
+        return false;
+      const body = buffer.slice(bodyStart, bodyEnd);
+      buffer = buffer.slice(bodyEnd);
+      await handle(JSON.parse(body), "content-length");
+      return true;
+    };
+    const parseLineMessage = async () => {
+      const lineEnd = buffer.indexOf(`
+`);
+      if (lineEnd < 0)
+        return false;
+      const line = buffer.slice(0, lineEnd).trim();
+      buffer = buffer.slice(lineEnd + 1);
+      if (!line)
+        return true;
+      await handle(JSON.parse(line), "newline");
+      return true;
+    };
+    const parse = async () => {
+      for (;; ) {
+        buffer = buffer.trimStart();
+        if (/^Content-Length:/i.test(buffer)) {
+          if (await parseContentLengthMessage())
+            continue;
+          return;
+        }
+        if (buffer.includes(`\r
+\r
+`) && await parseContentLengthMessage())
+          continue;
+        if (await parseLineMessage())
+          continue;
+        return;
+      }
+    };
+    for await (const chunk of Bun.stdin.stream()) {
+      buffer += decoder.decode(chunk);
+      await parse();
+    }
+  }
+  explainCommand(command) {
+    const explanations = {
+      context: "`akan context` prints agent-readable workspace, app, module, and abstract metadata.",
+      "create-module": "`akan create-module <name> --app <app>` scaffolds a database-backed domain module.",
+      "create-scalar": "`akan create-scalar <name> --app <app>` scaffolds a reusable scalar value module.",
+      "create-service": "`akan create-service <name> --app <app>` scaffolds a non-database service module.",
+      "create-view": "`akan create-view --app <app> --module <module>` creates a module View component.",
+      "create-unit": "`akan create-unit --app <app> --module <module>` creates a module Unit component.",
+      "create-template": "`akan create-template --app <app> --module <module>` creates a module Template component.",
+      "create-ui": "`akan create-ui --app <app-or-lib> --module <module> --surface <view|unit|template> --format json` creates one UI surface and returns a primitive write report.",
+      "add-field": "`akan add-field --app <app-or-lib> --module <module> --field <field> --type <String|Boolean|Date|Int|Float|scalar> --format json` updates source constant/dictionary files. Use Int or Float for numeric fields, not Number.",
+      "add-enum-field": "`akan add-enum-field --app <app-or-lib> --module <module> --field <field> --values a,b --format json` adds an enum field to source constant/dictionary files without editing generated files.",
+      sync: "`akan sync <app-or-lib>` refreshes generated Akan files from source conventions.",
+      lint: "`akan lint <app-or-lib-or-pkg>` runs Biome linting after preparing generated files.",
+      typecheck: "`akan typecheck <app-name>` runs an application typecheck after preparing generated files.",
+      test: "`akan test <app-or-lib-or-pkg>` prepares the target and runs its tests.",
+      build: "`akan build <app-name>` creates a production build after preparing generated files.",
+      doctor: "`akan doctor --strict --format json` reports agent-readable workspace convention diagnostics and validation hints.",
+      "guideline show": "`akan guideline show <name>` prints an Akan codegen guideline instruction.",
+      workflow: "`akan workflow list|explain|plan|apply|validate|report` lists, plans, applies, validates, and reports agent-readable Akan workflows.",
+      "workflow list": "`akan workflow list` lists parseable read-only workflow specs.",
+      "workflow explain": "`akan workflow explain <workflow>` explains inputs, optional surfaces, steps, and validation.",
+      "workflow plan": "`akan workflow plan <workflow> ... --out .akan/workflows/plans/<name>.json --format json` returns a read-only plan and can store a local plan artifact.",
+      "workflow apply": "`akan workflow apply [--dry-run] <plan-path> --format json` reads an approved plan artifact and returns a workflow apply report.",
+      "workflow validate": "`akan workflow validate <run-id-or-plan> --format json` runs validation commands from a plan or apply report and stores a structured run report.",
+      "workflow report": "`akan workflow report <run-id> --format json` reads .akan/workflows/runs/<run-id>.json and prints the stored report.",
+      repair: "`akan repair generated|format|imports|dictionary|module-shape --format json` runs narrow safe repairs or returns repair-oriented next actions.",
+      "repair generated": "`akan repair generated --app <app-or-lib> --format json` refreshes generated Akan files.",
+      "repair format": "`akan repair format --target <app-or-lib-or-pkg> --format json` runs the lint/format repair path.",
+      "repair imports": "`akan repair imports --target <app-or-lib-or-pkg> --format json` runs the import organization repair path.",
+      "repair dictionary": "`akan repair dictionary --app <app-or-lib> --module <module> --format json` reports dictionary label repair candidates.",
+      "repair module-shape": "`akan repair module-shape --app <app-or-lib> --module <module> --format json` reports missing module source files and source-safe next actions.",
+      agent: "`akan agent install <target>` writes editor-specific agent rules with overwrite protection.",
+      mcp: "`akan mcp --mode readonly|plan|apply` starts the Akan MCP server over stdio with an explicit permission mode.",
+      "mcp-call": '`akan mcp-call <tool> --mode plan --args \'{"workflow":"add-field","inputs":{"app":"demo"}}\'` calls one MCP tool through the same runner path for debugging.',
+      "mcp-install": "`akan mcp-install [cursor|claude|codex|all] --mode readonly|plan|apply` installs the Akan MCP server config for Cursor (.cursor/mcp.json), Claude Code (.mcp.json), and Codex (.codex/config.toml). Defaults to all targets."
+    };
+    return explanations[command] ?? `No detailed explanation is available for ${command}. Run \`akan --help\` for command help.`;
+  }
+}
+
+// pkgs/@akanjs/cli/context/context.script.ts
+var resolveMcpInstallTargets = (target) => {
+  if (!target || target === "all")
+    return [...akanMcpInstallTargets];
+  if (akanMcpInstallTargets.includes(target))
+    return [target];
+  throw new Error(`Unknown MCP install target: ${target}. Use cursor, claude, codex, or all.`);
+};
+var mcpTargetLabels = {
+  cursor: "Cursor",
+  claude: "Claude Code",
+  codex: "Codex"
+};
+
+class ContextScript extends script("context", [ContextRunner]) {
+  async context(workspace, options = {}) {
+    Logger.rawLog(await this.contextRunner.getContext(workspace, options));
+  }
+  async doctor(workspace, options = {}) {
+    Logger.rawLog(await this.contextRunner.doctor(workspace, options));
+  }
+  async mcpInstall(workspace, target, { force = false, mode = "apply" } = {}) {
+    const targets = resolveMcpInstallTargets(target);
+    const written = [];
+    for (const t of targets) {
+      const configPath = await this.contextRunner.installMcp(workspace, t, { force, mode });
+      written.push(`${mcpTargetLabels[t]}: ${configPath}`);
+    }
+    Logger.rawLog(`Akan MCP server installed (${mode} mode):
+${written.map((line) => `- ${line}`).join(`
+`)}`);
+  }
+  async mcp(workspace, { mode = "apply" } = {}) {
+    await this.contextRunner.runMcp(workspace, { mode });
+  }
+  async mcpCall(workspace, tool, {
+    mode = "readonly",
+    args = null,
+    format = "json"
+  } = {}) {
+    let parsedArgs = {};
+    if (args) {
+      const parsed = JSON.parse(args);
+      if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new Error("MCP call args must be a JSON object.");
+      }
+      parsedArgs = parsed;
+    }
+    const result = await this.contextRunner.callMcpTool(workspace, tool, parsedArgs, { mode });
+    Logger.rawLog(format === "json" ? jsonText(result) : String(result));
+  }
+}
+
+export { ContextScript };