akm-cli 0.9.0-rc.9 → 0.9.1-beta.1

package/dist/commands/proposal/proposal.js

@@ -13,8 +13,9 @@
  */
 import { resolveStashDir } from "../../core/common.js";
 import { loadConfig } from "../../core/config/config.js";
+import { resolveWriteTarget } from "../../core/write-source.js";
 import { withAssetMutationLease } from "../../indexer/index-writer-lock.js";
-import { createProposal, diffProposal, getProposal, isProposalSkipped, listProposals, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, revertProposal, } from "./repository.js";
+import { createProposal, diffProposal, isProposalSkipped, listProposals, preflightProposalPromotion, promoteProposal, proposalContent, recoverProposalTransactionsForStash, rejectProposalDurably, resolveProposalId, resolveProposalIdForReject, revertProposal, } from "./repository.js";
 import { validateProposal } from "./validators/proposals.js";
 // ── Shared helpers ──────────────────────────────────────────────────────────
 function resolveStash(stashDir) {
@@ -22,6 +23,14 @@ function resolveStash(stashDir) {
         return stashDir;
     return resolveStashDir();
 }
+function resolveProposalQueue(stashDir, queue, config) {
+    if (stashDir)
+        return { stashDir };
+    if (!queue)
+        return { stashDir: resolveStash() };
+    const target = resolveWriteTarget(config ?? loadConfig(), queue);
+    return { stashDir: target.source.path, target };
+}
 /**
  * Thin in-process read of the pending proposal queue, used by the health HTML
  * report builder (#582) so it never shells out to `akm proposal list`.
@@ -34,7 +43,7 @@ export function listPendingProposals(stashDir) {
     return listProposals(resolveStash(stashDir), { status: "pending" });
 }
 export function akmProposalList(options = {}) {
-    const stash = resolveStash(options.stashDir);
+    const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, options.config);
     // `--status accepted|rejected|reverted` implies archive-inclusion since the
     // live queue only ever contains pending entries.
     const includeArchive = options.includeArchive === true ||
@@ -50,19 +59,37 @@ export function akmProposalList(options = {}) {
     return { schemaVersion: 1, totalCount: proposals.length, proposals };
 }
 export function akmProposalShow(options) {
-    const stash = resolveStash(options.stashDir);
-    const proposal = getProposal(stash, options.id);
+    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const stash = queue.stashDir;
+    const proposal = resolveProposalId(stash, options.id);
+    let validation = validateProposal(proposal);
+    // An explicit stashDir without config is an in-process storage test seam; it
+    // has no authenticated write-target context to preflight against.
+    if (validation.ok &&
+        proposal.status === "pending" &&
+        (options.config !== undefined || options.stashDir === undefined)) {
+        try {
+            preflightProposalPromotion(options.config ?? loadConfig(), proposal, { queueTarget: queue.target });
+        }
+        catch (error) {
+            validation = {
+                ok: false,
+                findings: [{ kind: "promotion", message: error instanceof Error ? error.message : String(error) }],
+            };
+        }
+    }
     return {
         schemaVersion: 1,
         proposal,
-        validation: validateProposal(proposal),
+        validation,
     };
 }
 export async function akmProposalAccept(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const resolvedId = resolveProposalId(stash, options.id).id;
-    const result = await promoteProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
+    const result = await promoteProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target, gateDecision: options.gateDecision }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -74,11 +101,14 @@ export async function akmProposalAccept(options) {
 }
 export async function akmProposalReject(options) {
     return withAssetMutationLease("proposal-reject", async () => {
-        const stash = resolveStash(options.stashDir);
         const config = options.config ?? loadConfig();
-        const proposalId = resolveProposalId(stash, options.id).id;
+        const { stashDir: stash } = resolveProposalQueue(options.stashDir, options.queue, config);
+        // resolveProposalIdForReject tolerates a legacy row whose metadata fails
+        // strict decoding — resolveProposalId's exact-UUID match would otherwise
+        // throw here, before the terminal-status machinery even runs.
+        const proposalId = resolveProposalIdForReject(stash, options.id, options.ctx);
         await recoverProposalTransactionsForStash(stash, config, options.ctx, proposalId);
-        const updated = rejectProposalDurably(stash, proposalId, options.reason, options.ctx);
+        const updated = rejectProposalDurably(stash, proposalId, options.reason, options.ctx, options.gateDecision);
         return {
             schemaVersion: 1,
             ok: true,
@@ -90,10 +120,11 @@ export async function akmProposalReject(options) {
     });
 }
 export function akmProposalDiff(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const proposal = resolveProposalId(stash, options.id);
-    const diff = diffProposal(stash, config, proposal.id, { target: options.target });
+    const diff = diffProposal(stash, config, proposal.id, { target: options.target, queueTarget: queue.target });
     return {
         schemaVersion: 1,
         id: proposal.id,
@@ -104,12 +135,15 @@ export function akmProposalDiff(options) {
     };
 }
 export function akmProposalCreate(options) {
-    const stash = resolveStash(options.stashDir);
+    const queue = resolveProposalQueue(options.stashDir, options.queue, options.config);
+    const stash = queue.stashDir;
+    const target = options.target ?? (queue.target ? { source: queue.target.source.name, root: queue.target.source.path } : undefined);
     // Manual proposal creation (via `akm proposal create`) always bypasses
     // dedup/cooldown guards — the operator is explicitly requesting a proposal.
     const result = createProposal(stash, {
         ref: options.ref,
         source: options.source,
+        ...(target !== undefined ? { target } : {}),
         ...(options.sourceRun !== undefined ? { sourceRun: options.sourceRun } : {}),
         payload: options.payload,
         force: true,
@@ -137,10 +171,11 @@ export function akmProposalCreate(options) {
  * `rejected`.
  */
 export async function akmProposalRevert(options) {
-    const stash = resolveStash(options.stashDir);
     const config = options.config ?? loadConfig();
+    const queue = resolveProposalQueue(options.stashDir, options.queue, config);
+    const stash = queue.stashDir;
     const resolvedId = resolveProposalId(stash, options.id).id;
-    const result = await revertProposal(stash, config, resolvedId, { target: options.target }, options.ctx);
+    const result = await revertProposal(stash, config, resolvedId, { target: options.target, queueTarget: queue.target }, options.ctx);
     return {
         schemaVersion: 1,
         ok: true,
@@ -158,7 +193,8 @@ export async function akmProposalRevert(options) {
  * dry-run record shape. The destructive-confirmation prompt stays CLI-side.
  */
 export async function bulkAdjudicateProposals(options) {
-    const stashDir = resolveStash(options.stashDir);
+    const config = options.config ?? loadConfig();
+    const { stashDir } = resolveProposalQueue(options.stashDir, options.queue, config);
     const pending = listProposals(stashDir, { status: "pending" }).filter((p) => {
         if (p.source !== options.generator)
             return false;
@@ -180,10 +216,10 @@ export async function bulkAdjudicateProposals(options) {
             results.push({ id: proposal.id, ref: proposal.ref, source: proposal.source, dryRun: true });
         }
         else if (options.action === "accept") {
-            results.push(await akmProposalAccept({ id: proposal.id, target: options.target }));
+            results.push(await akmProposalAccept({ stashDir, id: proposal.id, queue: options.queue, target: options.target, config }));
         }
         else {
-            results.push(await akmProposalReject({ id: proposal.id, reason: options.reason }));
+            results.push(await akmProposalReject({ stashDir, id: proposal.id, queue: options.queue, reason: options.reason, config }));
         }
     }
     return { count: results.length, results };

package/dist/commands/proposal/propose-cli.js

@@ -0,0 +1,88 @@
+// This Source Code Form is subject to the terms of the Mozilla Public
+// License, v. 2.0. If a copy of the MPL was not distributed with this
+// file, You can obtain one at https://mozilla.org/MPL/2.0/.
+/**
+ * `akm proposal new` — the asset-authoring entry point (formerly the
+ * top-level `akm propose`, moved under the `proposal` group per the 0.9 CLI
+ * overhaul, S8). Shares no private helper with the proposal MANAGEMENT
+ * family (list/show/accept/reject/…, `./proposal-cli.ts`) — its path/name
+ * helpers come from the shared src/core/asset/asset-create.ts module.
+ *
+ * Keeps the inline `runWithJsonErrors` form (branches on the result and sets
+ * `process.exitCode` conditionally on a failed proposal) rather than
+ * migrating to `defineJsonCommand`, matching the original contribute-cli.ts
+ * rationale: `process.exitCode` (not `process.exit()`) so the process still
+ * exits via natural event-loop drain rather than skipping pending cleanup.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { defineCommand } from "citty";
+import { getStringArg, parsePositiveIntFlag } from "../../cli/parse-args.js";
+import { EXIT_CODES, GLOBAL_OUTPUT_ARGS, output, runWithJsonErrors } from "../../cli/shared.js";
+import { assertFlatAssetName, combineCreatePath, normalizeCreateSubPath } from "../../core/asset/asset-create.js";
+import { UsageError } from "../../core/errors.js";
+import { akmPropose } from "./propose.js";
+const EXIT_GENERAL = EXIT_CODES.GENERAL;
+export const proposeCommand = defineCommand({
+    meta: {
+        name: "new",
+        description: "Ask the configured agent CLI to author a brand-new asset and queue it as a proposal",
+    },
+    // Raw defineCommand: declare the global output flags so their space-separated
+    // values are consumed rather than shifting the `type` / `name` positionals.
+    args: {
+        ...GLOBAL_OUTPUT_ARGS,
+        // Optional in citty so run() is invoked when omitted; we re-validate
+        // below to surface a structured UsageError (exit 2) instead of citty's
+        // default help-banner exit-0.
+        type: { type: "positional", description: "Asset type (skill, command, knowledge, lesson, ...)", required: false },
+        name: {
+            type: "positional",
+            description: "Asset name (flat, no '/'; use --path for a subdirectory)",
+            required: false,
+        },
+        path: {
+            type: "string",
+            description: "Relative subdirectory under the type dir to place the proposed asset in (e.g. 'release'). The filename comes from the name.",
+        },
+        task: { type: "string", description: "Task description for the agent (what should the asset do?)" },
+        file: { type: "string", description: "Read the task or prompt text from a UTF-8 file" },
+        engine: { type: "string", description: "Engine to use (defaults to defaults.engine)" },
+        "timeout-ms": { type: "string", description: "Override the agent CLI timeout in milliseconds" },
+    },
+    async run({ args }) {
+        await runWithJsonErrors(async () => {
+            // citty silently shows help and exits 0 when required positionals are
+            // omitted. Re-validate explicitly so the exit code is 2 (USAGE) and a
+            // structured JSON error reaches scripted callers.
+            const taskFromFlag = typeof args.task === "string" ? args.task : undefined;
+            const fileFromFlag = typeof args.file === "string" ? args.file : undefined;
+            if (!args.type || !args.name || (!taskFromFlag && !fileFromFlag)) {
+                throw new UsageError("Usage: akm proposal new <type> <name> (--task '<task>' | --file <path>).", "MISSING_REQUIRED_ARGUMENT", "Provide the asset type, name, and exactly one of --task or --file.");
+            }
+            if (taskFromFlag && fileFromFlag) {
+                throw new UsageError("Pass exactly one of --task or --file.", "INVALID_FLAG_VALUE");
+            }
+            // `name` is flat; subdirectory placement is `--path`'s job.
+            assertFlatAssetName(String(args.name));
+            const proposedName = combineCreatePath(normalizeCreateSubPath(getStringArg(args, "path")), String(args.name));
+            const taskText = fileFromFlag ? fs.readFileSync(path.resolve(fileFromFlag), "utf8") : (taskFromFlag ?? "");
+            const timeoutMs = parsePositiveIntFlag(args["timeout-ms"], "--timeout-ms");
+            const result = await akmPropose({
+                type: String(args.type),
+                name: proposedName,
+                task: taskText,
+                engine: getStringArg(args, "engine"),
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+            });
+            output("proposal-new", result);
+            if (result.ok === false) {
+                // Same reasoning as agentCommand in contribute-cli.ts: output() already
+                // ran, this is the last statement in the handler, so process.exitCode +
+                // return is equivalent without skipping any pending cleanup.
+                process.exitCode = EXIT_GENERAL;
+                return;
+            }
+        });
+    },
+});

package/dist/commands/proposal/propose.js

@@ -20,12 +20,14 @@ import { ConfigError, UsageError } from "../../core/errors.js";
 import { appendEvent } from "../../core/events.js";
 import { redactSensitiveText } from "../../core/redaction.js";
 import { resolveStandardsContext } from "../../core/standards/resolve-standards-context.js";
-import { deriveEntryProvenance, deriveInstallations, slugForPath } from "../../indexer/installations.js";
+import { warn } from "../../core/warn.js";
+import { deriveEntryProvenance } from "../../indexer/installations.js";
+import { fallbackAnnouncement, NO_ENGINE_MESSAGE_SUFFIX, NO_ENGINE_REMEDY, withEngineFallback, } from "../../integrations/agent/engine-fallback.js";
 import { resolveEngine } from "../../integrations/agent/engine-resolution.js";
 import { buildProposePrompt, parseAgentProposalPayload } from "../../integrations/agent/prompts.js";
 import { collectDispatchSensitiveValues, executeRunner } from "../../integrations/agent/runner-dispatch.js";
 import { baseFailureFields, enoentHintMessage, isEnoentFailure } from "../agent/agent-support.js";
-import { createProposal, isProposalSkipped, } from "./repository.js";
+import { createProposal, isProposalSkipped, resolveProposalQueueTarget, } from "./repository.js";
 function failureEnvelope(result, type, name, engine, fallbackReason = "non_zero_exit") {
     return {
         ...baseFailureFields(result, fallbackReason),
@@ -44,8 +46,7 @@ function failureEnvelope(result, type, name, engine, fallbackReason = "non_zero_
  * uses). Matches `createProposal`'s durable `proposals.ref` mint, so the entry
  * event, the fallback ref, and the stored proposal all carry one spelling.
  */
-function proposeItemRef(stashDir, type, name) {
-    const bundleId = deriveInstallations([{ path: stashDir, writable: true }])[0]?.id ?? slugForPath(stashDir);
+function proposeItemRef(bundleId, type, name) {
     return deriveEntryProvenance({ bundleId, componentId: bundleId, adapterId: "akm" }, type, name).itemRef;
 }
 /**
@@ -53,10 +54,10 @@ function proposeItemRef(stashDir, type, name) {
  * fully-qualified item_ref the durable proposal is minted under
  * (`proposeItemRef`), so the entry event and the stored proposal agree.
  */
-function emitProposeInvoked(stash, options) {
+function emitProposeInvoked(bundleId, options) {
     appendEvent({
         eventType: "propose_invoked",
-        ref: proposeItemRef(stash, options.type, options.name),
+        ref: proposeItemRef(bundleId, options.type, options.name),
         metadata: {
             type: options.type,
             name: options.name,
@@ -79,15 +80,21 @@ export async function akmPropose(options) {
         throw new UsageError(`propose: unknown asset type "${options.type}". Known types: ${[...placementTypes()].sort().join(", ")}.`, "INVALID_FLAG_VALUE");
     }
     const stash = options.stashDir ?? resolveStashDir();
-    // 1. Always emit `propose_invoked` (extracted: emitProposeInvoked).
-    emitProposeInvoked(stash, options);
-    // 2. Resolve the selected engine exactly once. Propose accepts either kind;
+    // 1. Resolve the selected engine and write target exactly once.
     // the LLM arm uses the caller-specific plain-chat handler below.
     const config = options.agentConfig ?? (await import("../../core/config/config.js")).loadConfig();
-    const engineName = options.engine ?? config.defaults?.engine;
+    const target = resolveProposalQueueTarget(stash, config);
+    emitProposeInvoked(target.source, options);
+    const { config: engineConfig, fallbackEngineName } = withEngineFallback(config);
+    const engineName = options.engine ?? engineConfig.defaults?.engine;
+    // Announced, never silent: `options.engine` outranks the default, so the
+    // fallback is only reportable when it is the engine actually selected.
+    const engineAnnouncement = fallbackAnnouncement(fallbackEngineName, engineName);
+    if (engineAnnouncement)
+        warn(engineAnnouncement);
     if (!engineName)
-        throw new ConfigError("propose requires --engine or defaults.engine.", "INVALID_CONFIG_FILE");
-    const runner = resolveEngine(engineName, config);
+        throw new ConfigError(`propose ${NO_ENGINE_MESSAGE_SUFFIX} ${NO_ENGINE_REMEDY}`, "INVALID_CONFIG_FILE");
+    const runner = resolveEngine(engineName, engineConfig);
     const profile = runner.kind === "llm" ? undefined : runner.profile;
     // 3. Build prompt.
     // Synthesize a temp draft path so opencode can write the asset content
@@ -158,7 +165,7 @@ export async function akmPropose(options) {
         const draftContent = fs.readFileSync(resolvedDraftPath, "utf8");
         fs.unlinkSync(resolvedDraftPath);
         payload = {
-            ref: proposeItemRef(stash, options.type, options.name), // WI-8.5a item_ref flip
+            ref: proposeItemRef(target.source, options.type, options.name),
             content: draftContent,
         };
     }
@@ -201,7 +208,7 @@ export async function akmPropose(options) {
     // 6. Insert the proposal. Note: we allow the agent's `ref` to normalise the
     // asset name (e.g. path-cleanup), but only after validating that the ref is
     // well-formed and the type still matches the requested type.
-    const expectedRef = proposeItemRef(stash, options.type, options.name); // WI-8.5a item_ref flip
+    const expectedRef = proposeItemRef(target.source, options.type, options.name);
     let ref = expectedRef;
     if (payload.ref) {
         let parsedRef;
@@ -236,12 +243,13 @@ export async function akmPropose(options) {
                 ...(result.stderr ? { stderr: result.stderr } : {}),
             };
         }
-        ref = proposeItemRef(stash, parsedRef.type, parsedRef.name); // WI-8.5a item_ref flip
+        ref = proposeItemRef(target.source, parsedRef.type, parsedRef.name);
     }
     const createInput = {
         ref,
         source: "propose",
         sourceRun: `propose-${Date.now()}`,
+        target,
         // User-initiated proposals always bypass dedup/cooldown guards — the
         // operator is explicitly asking for a new proposal.
         force: true,