perttool 0.3.0 → 0.4.0

package/dist/cli.js

@@ -6,16 +6,19 @@ import { analyzeDocument, selectNextTasks, } from "./application/contract4.js";
 import { checkDocument } from "./application/check.js";
 import { planFormat } from "./application/format.js";
 import { planProjectInit, projectInitResultToJson, renderProjectInitResult, withProjectInitOutput, } from "./application/init.js";
-import { planBatchMutation, planMutation } from "./application/mutate.js";
 import { planUnitMigration, withUnitMigrationWrite, } from "./application/unit-migration.js";
 import { getProjectMetadata, } from "./application/project.js";
+import { planTargetGovernanceAdvance, planTargetGovernanceBatchMutation, planTargetGovernanceMutation, } from "./application/target-governance-mutation.js";
+import { renderTargetGovernanceDecision, renderTargetGovernanceProjectText, targetGovernanceMutationResultToJson, targetGovernanceProjectResultToJson, } from "./application/target-governance-projection.js";
+import { persistTargetGovernanceResult, } from "./application/target-governance-write.js";
 import { getAgentHelp } from "./application/agent-help.js";
 import { exportMermaid, } from "./conversion/mermaid.js";
 import { importMermaid } from "./conversion/mermaid-import.js";
-import { getGuide, renderGuideResult, serializeGuideResult, } from "./help/guide.js";
+import { getTargetGovernanceGuide, renderTargetGovernanceGuideResult, serializeTargetGovernanceGuideResult, } from "./help/target-governance-guide.js";
 import { commandOptionSets, } from "./command/registry.js";
-import { CONTRACT4_COMMAND_REGISTRY, getCommandDiscovery, renderCommandHelpResult, serializeCommandHelpResult, } from "./command/discovery.js";
-import { handlerCommandUsageError, renderCommandUsageError, serializeCommandUsageError, validateCommandInvocation, } from "./command/usage.js";
+import { TARGET_GOVERNANCE_COMMAND_REGISTRY, getTargetGovernanceCommandDiscovery, renderTargetGovernanceCommandHelpResult, serializeTargetGovernanceCommandHelpResult, } from "./command/target-governance-discovery.js";
+import { handlerCommandUsageError, } from "./command/usage.js";
+import { renderTargetGovernanceCommandUsageError, serializeTargetGovernanceCommandUsageError, validateTargetGovernanceCommandInvocation, } from "./command/target-governance-usage.js";
 import { agentGuidanceResultToJson } from "./guidance/projection.js";
 import { agentGuidanceExitCode, renderAgentGuidanceText, } from "./guidance/text.js";
 import { documentContentFromBytes, readDocumentFile, } from "./io/document-file.js";
@@ -24,7 +27,7 @@ import { formatDecimal } from "./model/rational.js";
 import { convertWithVelocity, durationSuffix } from "./model/units.js";
 import { recommendationInvariantExitCode } from "./recommendation/failure.js";
 import { recommendationAnalysisToJson } from "./recommendation/json.js";
-import { planAdvance, } from "./mutation/advance.js";
+import { TARGET_GRAMMAR_4_CAPABILITY, } from "./parser/document-parser.js";
 import { TOOL_VERSION } from "./version.js";
 class UsageError extends Error {
     code = "PTCLI-001";
@@ -79,7 +82,7 @@ function parseOptions(args, valueOptions, flagOptions, repeatableOptions = new S
     return { positionals, values, repeatedValues, flags };
 }
 function parseCommandOptions(operation, args) {
-    const descriptor = CONTRACT4_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
+    const descriptor = TARGET_GOVERNANCE_COMMAND_REGISTRY.find((candidate) => candidate.operation === operation);
     if (descriptor === undefined) {
         throw new Error(`command descriptor is missing for ${operation}`);
     }
@@ -217,7 +220,7 @@ function cliError(error, exitCode, operation, json) {
     if (json) {
         writeJson({
             schema_version: "Perttool.CliError.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation,
             ok: false,
@@ -253,7 +256,7 @@ async function runCheck(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.CheckResult.v2",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "document.check",
             ok,
@@ -280,41 +283,6 @@ async function runCheck(args) {
     }
     return ok ? 0 : 1;
 }
-function projectJson(project) {
-    return {
-        id: project.id,
-        version: project.version,
-        title: project.title,
-        description: project.description,
-        as_of: snakeJson(project.asOf),
-        duration_unit: project.durationUnit,
-        velocity: project.velocity,
-        finish: project.finish,
-        finish_deadline: snakeJson(project.finishDeadline),
-        critical_epsilon: project.criticalEpsilon,
-        target_duration: project.targetDuration,
-    };
-}
-function renderProjectText(project) {
-    const optional = (value) => value ?? "-";
-    const calendar = (value) => value === null
-        ? "-"
-        : `${value.kind.toUpperCase()} ${value.sourceText ?? "-"}`;
-    return [
-        `PROJECT ${project.id}`,
-        `VERSION ${project.version}`,
-        `TITLE ${JSON.stringify(project.title)}`,
-        `DESCRIPTION ${project.description === null ? "-" : JSON.stringify(project.description)}`,
-        `AS_OF ${calendar(project.asOf)}`,
-        `DURATION_UNIT ${project.durationUnit}`,
-        `VELOCITY ${optional(project.velocity)}`,
-        `FINISH ${project.finish}`,
-        `FINISH_DEADLINE ${calendar(project.finishDeadline)}`,
-        `CRITICAL_EPSILON ${optional(project.criticalEpsilon)}`,
-        `TARGET_DURATION ${optional(project.targetDuration)}`,
-        "",
-    ].join("\n");
-}
 async function runProjectShow(args) {
     const parsed = parseCommandOptions("project.show", args);
     if (parsed.positionals.length !== 1) {
@@ -338,24 +306,11 @@ async function runProjectShow(args) {
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.ProjectResult.v2",
-            cli_contract_version: 4,
-            tool_version: TOOL_VERSION,
-            operation: "project.show",
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            grammar_version: result.grammarVersion,
-            project: result.project === null ? null : projectJson(result.project),
-        });
+        writeJson(targetGovernanceProjectResultToJson(result, source, input.digest, ok));
     }
     else {
         if (ok && result.project !== null) {
-            process.stdout.write(renderProjectText(result.project));
+            process.stdout.write(renderTargetGovernanceProjectText(result.project));
         }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
@@ -391,6 +346,22 @@ async function runProjectInit(args) {
             : {
                 initialMilestoneDeadline: parsed.values.get("initial-milestone-deadline"),
             }),
+        ...(parsed.values.get("goal-owner") === undefined
+            ? {}
+            : { goalOwner: parsed.values.get("goal-owner") }),
+        ...(parsed.values.get("goal-delegates") === undefined
+            ? {}
+            : {
+                goalDelegates: principalListOption(parsed.values.get("goal-delegates")),
+            }),
+        ...(parsed.values.get("dag-owner") === undefined
+            ? {}
+            : { dagOwner: parsed.values.get("dag-owner") }),
+        ...(parsed.values.get("dag-delegates") === undefined
+            ? {}
+            : {
+                dagDelegates: principalListOption(parsed.values.get("dag-delegates")),
+            }),
     });
     let writeResult = null;
     const output = parsed.values.get("out");
@@ -494,6 +465,39 @@ function editingWriteRequest(parsed, sourceOperand, check = false) {
         return { mode: "out", target: out };
     return { mode: "preview", target: null };
 }
+function governanceRequest(parsed, writeRequest) {
+    return Object.freeze({
+        intent: writeRequest.mode === "preview"
+            ? "preview"
+            : "persist",
+        actor: parsed.values.get("actor") ?? null,
+        acceptedByOwner: Object.freeze([
+            ...(parsed.repeatedValues.get("accepted-by-owner") ?? []),
+        ]),
+    });
+}
+async function persistGovernedResult(result, request, sourceOperand) {
+    if (request.mode === "preview") {
+        return Object.freeze({
+            mode: "preview",
+            target: null,
+            written: false,
+        });
+    }
+    return persistTargetGovernanceResult(result, TARGET_GRAMMAR_4_CAPABILITY, request.mode === "in_place"
+        ? {
+            mode: "in_place",
+            target: request.target,
+            ...(request.expectedDigest === undefined
+                ? {}
+                : { expectedDigest: request.expectedDigest }),
+        }
+        : {
+            mode: "out",
+            source: sourceOperand,
+            target: request.target,
+        });
+}
 function assertExpectedDigest(request, initialDigest) {
     if (request.mode === "in_place" &&
         request.expectedDigest !== undefined &&
@@ -526,6 +530,9 @@ function writeFailureExit(error, operation, json) {
 function renderWriteSummary(operation, result) {
     return `WRITE ${operation} mode=${result.mode} target=${result.target} digest=${result.digest} written=${result.written}\n`;
 }
+function renderGovernanceWriteSummary(operation, result, digest) {
+    return `WRITE ${operation} mode=${result.mode} target=${result.target ?? "-"} digest=${digest ?? "-"} written=${result.written}\n`;
+}
 async function runFormat(args) {
     const parsed = parseCommandOptions("document.format", args);
     if (parsed.positionals.length !== 1) {
@@ -569,7 +576,7 @@ async function runFormat(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.FormatResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "document.format",
             ok,
@@ -637,6 +644,12 @@ function uniqueRepeated(parsed, option) {
     }
     return values;
 }
+function principalListOption(value) {
+    const interior = value.slice(1, -1).trim();
+    return interior === ""
+        ? Object.freeze([])
+        : Object.freeze(interior.split(",").map((item) => item.trim()));
+}
 function enumRepeated(parsed, option, allowed) {
     return uniqueRepeated(parsed, option).map((value) => {
         if (!allowed.has(value)) {
@@ -823,6 +836,10 @@ function projectMutationFromOptions(parsed) {
         "velocity",
         "critical_epsilon",
         "target_duration",
+        "goal_owner",
+        "goal_delegates",
+        "dag_owner",
+        "dag_delegates",
     ]));
     const conflicts = new Map([
         ["description", parsed.values.has("description")],
@@ -830,6 +847,10 @@ function projectMutationFromOptions(parsed) {
         ["velocity", parsed.values.has("velocity")],
         ["critical_epsilon", parsed.values.has("critical-epsilon")],
         ["target_duration", parsed.values.has("target-duration")],
+        ["goal_owner", parsed.values.has("goal-owner")],
+        ["goal_delegates", parsed.values.has("goal-delegates")],
+        ["dag_owner", parsed.values.has("dag-owner")],
+        ["dag_delegates", parsed.values.has("dag-delegates")],
     ]);
     const conflict = clear.find((field) => conflicts.get(field) === true);
     if (conflict !== undefined) {
@@ -860,6 +881,22 @@ function projectMutationFromOptions(parsed) {
         ...(parsed.values.get("target-duration") === undefined
             ? {}
             : { targetDuration: parsed.values.get("target-duration") }),
+        ...(parsed.values.get("goal-owner") === undefined
+            ? {}
+            : { goalOwner: parsed.values.get("goal-owner") }),
+        ...(parsed.values.get("goal-delegates") === undefined
+            ? {}
+            : {
+                goalDelegates: principalListOption(parsed.values.get("goal-delegates")),
+            }),
+        ...(parsed.values.get("dag-owner") === undefined
+            ? {}
+            : { dagOwner: parsed.values.get("dag-owner") }),
+        ...(parsed.values.get("dag-delegates") === undefined
+            ? {}
+            : {
+                dagDelegates: principalListOption(parsed.values.get("dag-delegates")),
+            }),
     };
     return {
         kind: "project.set",
@@ -1084,20 +1121,24 @@ async function runMutation(resource, action, args) {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
+        governance: governanceRequest(parsed, writeRequest),
     };
     const result = resource === "batch"
-        ? planBatchMutation(input.text, mutation, mutationOptions)
-        : planMutation(input.text, mutation, mutationOptions);
+        ? planTargetGovernanceBatchMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, mutationOptions)
+        : planTargetGovernanceMutation(input.text, mutation, TARGET_GRAMMAR_4_CAPABILITY, mutationOptions);
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
-    let writeResult = null;
+    let writeResult = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
     if (result.ok) {
         try {
-            assertExpectedDigest(writeRequest, input.digest);
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await commitCandidate(writeRequest, result.updatedText, input.digest);
+                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
             }
         }
         catch (error) {
@@ -1105,24 +1146,12 @@ async function runMutation(resource, action, args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 4,
-            tool_version: TOOL_VERSION,
-            operation,
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            ...previewResultJson(result, result.ok, writeRequest, writeResult),
-        });
+        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), operation, source, writeResult));
     }
     else {
         if (ok) {
-            if (writeResult !== null) {
-                process.stderr.write(renderWriteSummary(operation, writeResult));
+            if (writeRequest.mode !== "preview") {
+                process.stderr.write(renderGovernanceWriteSummary(operation, writeResult, result.updatedDigest));
             }
             else {
                 process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
@@ -1131,6 +1160,9 @@ async function runMutation(resource, action, args) {
                 }
             }
         }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
@@ -1148,7 +1180,7 @@ function unitMigrationJson(result, source, sourceDigest, ok) {
     });
     return {
         schema_version: result.schemaVersion,
-        cli_contract_version: 4,
+        cli_contract_version: 5,
         tool_version: TOOL_VERSION,
         operation: "project.migrate-unit",
         ok,
@@ -1276,19 +1308,6 @@ async function runUnitMigration(args) {
     }
     return ok ? 0 : 1;
 }
-function advanceResultJson(details) {
-    return details === null
-        ? null
-        : {
-            removed_task_ids: details.removedTaskIds,
-            removed_gate_ids: details.removedGateIds,
-            removed_milestone_ids: details.removedMilestoneIds,
-            frontier_before: details.frontierBefore,
-            frontier_after: details.frontierAfter,
-            ready_before: details.readyBefore,
-            ready_after: details.readyAfter,
-        };
-}
 function renderAdvanceSummary(details) {
     const list = (ids) => ids.join(",") || "-";
     return [
@@ -1315,21 +1334,25 @@ async function runAdvance(args) {
     catch (error) {
         return cliError(error instanceof Error ? error : new Error(String(error)), 3, "dag.advance", format === "json");
     }
-    const result = planAdvance(input.text, {
+    const result = planTargetGovernanceAdvance(input.text, TARGET_GRAMMAR_4_CAPABILITY, {
         maxDiagnostics,
         originalLabel: source,
         updatedLabel: "candidate",
+        governance: governanceRequest(parsed, writeRequest),
     });
     const warningFailure = parsed.flags.has("warnings-as-errors") &&
         (result.diagnosticsTruncated ||
             result.diagnostics.some((diagnostic) => diagnostic.severity === "warning"));
     const ok = result.ok && !warningFailure;
-    let writeResult = null;
+    let writeResult = Object.freeze({
+        mode: writeRequest.mode,
+        target: writeRequest.target,
+        written: false,
+    });
     if (result.ok) {
         try {
-            assertExpectedDigest(writeRequest, input.digest);
             if (ok && writeRequest.mode !== "preview") {
-                writeResult = await commitCandidate(writeRequest, result.updatedText, input.digest);
+                writeResult = await persistGovernedResult(result, writeRequest, sourceOperand);
             }
         }
         catch (error) {
@@ -1337,25 +1360,12 @@ async function runAdvance(args) {
         }
     }
     if (format === "json") {
-        writeJson({
-            schema_version: "Perttool.MutationResult.v1",
-            cli_contract_version: 4,
-            tool_version: TOOL_VERSION,
-            operation: "dag.advance",
-            ok,
-            document_id: result.documentId,
-            source,
-            source_digest: input.digest,
-            diagnostics: result.diagnostics.map(jsonDiagnostic),
-            diagnostics_truncated: result.diagnosticsTruncated,
-            ...previewResultJson(result, result.ok, writeRequest, writeResult),
-            advance: advanceResultJson(result.advance),
-        });
+        writeJson(targetGovernanceMutationResultToJson(ok ? result : Object.freeze({ ...result, ok: false }), "dag.advance", source, writeResult));
     }
     else {
         if (ok && result.advance !== null) {
-            if (writeResult !== null) {
-                process.stderr.write(renderWriteSummary("dag.advance", writeResult));
+            if (writeRequest.mode !== "preview") {
+                process.stderr.write(renderGovernanceWriteSummary("dag.advance", writeResult, result.updatedDigest));
             }
             else {
                 process.stdout.write(parsed.flags.has("diff") ? (result.diff ?? "") : (result.updatedText ?? ""));
@@ -1365,6 +1375,9 @@ async function runAdvance(args) {
             }
             process.stderr.write(renderAdvanceSummary(result.advance));
         }
+        if (result.governance !== null) {
+            process.stderr.write(renderTargetGovernanceDecision(result.governance));
+        }
         for (const diagnostic of result.diagnostics) {
             process.stderr.write(`${renderDiagnostic(diagnostic, source, color)}\n`);
         }
@@ -1689,7 +1702,7 @@ async function runAnalyze(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.AnalysisResult.v3",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.analyze",
             ok,
@@ -1803,7 +1816,7 @@ async function runRender(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ExportResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.render",
             ok,
@@ -1895,7 +1908,7 @@ async function runImport(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.ImportResult.v1",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             tool_version: TOOL_VERSION,
             operation: "dag.import",
             ok,
@@ -2202,7 +2215,7 @@ async function runNext(args) {
         if (format === "json") {
             writeJson({
                 schema_version: "Perttool.CliError.v1",
-                cli_contract_version: 4,
+                cli_contract_version: 5,
                 tool_version: TOOL_VERSION,
                 operation: "dag.next",
                 ok: false,
@@ -2223,7 +2236,7 @@ async function runNext(args) {
     if (format === "json") {
         writeJson({
             schema_version: "Perttool.NextResult.v4",
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             recommendation_interface_version: 1,
             tool_version: TOOL_VERSION,
             operation: "dag.next",
@@ -2259,12 +2272,12 @@ function runGuide(args) {
     colorMode(parsed.values.get("color"), format);
     const topicId = parsed.positionals.length === 0 ? null : parsed.positionals.join(".");
     const level = helpLevel(parsed.values.get("level"), topicId !== null);
-    const result = getGuide(topicId, level);
+    const result = getTargetGovernanceGuide(topicId, level);
     if (format === "json") {
-        process.stdout.write(serializeGuideResult(result));
+        process.stdout.write(serializeTargetGovernanceGuideResult(result));
     }
     else {
-        const rendered = renderGuideResult(result);
+        const rendered = renderTargetGovernanceGuideResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2280,15 +2293,15 @@ function runCommandHelp(args) {
         throw new UsageError("help accepts at most <resource> <action>");
     }
     const format = outputFormat(parsed.values.get("format"));
-    const result = getCommandDiscovery({
+    const result = getTargetGovernanceCommandDiscovery({
         resource: parsed.positionals[0] ?? null,
         action: parsed.positionals[1] ?? null,
     });
     if (format === "json") {
-        process.stdout.write(serializeCommandHelpResult(result));
+        process.stdout.write(serializeTargetGovernanceCommandHelpResult(result));
     }
     else {
-        const rendered = renderCommandHelpResult(result);
+        const rendered = renderTargetGovernanceCommandHelpResult(result);
         if (result.ok) {
             process.stdout.write(rendered);
         }
@@ -2318,7 +2331,7 @@ function runAgentHelp(args) {
         const { schema_version: schemaVersion, ...payload } = projected;
         writeJson({
             schema_version: schemaVersion,
-            cli_contract_version: 4,
+            cli_contract_version: 5,
             ...payload,
         });
     }
@@ -2376,14 +2389,14 @@ async function dispatchCommand(descriptor, args) {
         const [resource, action] = descriptor.path;
         return runMutation(resource, action, args);
     }
-    throw new Error(`no Contract 4 handler for ${descriptor.operation}`);
+    throw new Error(`no Contract 5 handler for ${descriptor.operation}`);
 }
 function emitCommandUsage(error, json) {
     if (json) {
-        process.stdout.write(serializeCommandUsageError(error));
+        process.stdout.write(serializeTargetGovernanceCommandUsageError(error));
     }
     else {
-        process.stderr.write(renderCommandUsageError(error));
+        process.stderr.write(renderTargetGovernanceCommandUsageError(error));
     }
     return 2;
 }
@@ -2395,13 +2408,13 @@ async function main(argv) {
     if (argv.length === 1 && argv[0] === "--help") {
         return runCommandHelp([]);
     }
-    const validation = validateCommandInvocation(argv);
+    const validation = validateTargetGovernanceCommandInvocation(argv);
     if (!validation.ok) {
         if (jsonRequested(argv)) {
-            process.stdout.write(serializeCommandUsageError(validation.error));
+            process.stdout.write(serializeTargetGovernanceCommandUsageError(validation.error));
         }
         else {
-            process.stderr.write(renderCommandUsageError(validation.error));
+            process.stderr.write(renderTargetGovernanceCommandUsageError(validation.error));
         }
         return 2;
     }