@astrosheep/keiyaku 4.6.7 → 4.6.9

package/build/src/cli/commands/debt-grammar.js

@@ -0,0 +1,323 @@
+import { CliUsageError, DEBT_FAMILY_USAGE_GUIDE, unknownCommandGuide } from "../usage.js";
+import { scanArgs } from "../scan.js";
+import { parseDebtNamespaceSelector } from "../../debt/catalog.js";
+import { parseDebtId } from "../../debt/identity.js";
+import { parseDebtQueryExpression, validateDebtLimit, validateDebtParent, } from "./debt-query.js";
+const COMMON = { json: "boolean" };
+const DEBT_COMMAND_SPECS = {
+    add: {
+        arity: [0, 1],
+        stdin: "document",
+        flags: {
+            ...COMMON,
+            namespace: "value",
+            state: "value",
+            priority: "value",
+            needs: "repeat",
+            parent: "value",
+            supersedes: "repeat",
+            relates: "repeat",
+            body: "value",
+            note: "value",
+            actor: "value",
+        },
+        usage: `debt add <TITLE> [--namespace <ns>] [--priority 0..3]
+  [--state open|done|drop]
+  [--note <text>] [--actor <actor>]
+  [--needs <DebtId>]... [--parent <DebtId>]
+  [--supersedes <DebtId>]... [--relates <DebtId>]...
+  [--body <text>]
+debt add [--namespace <ns>] [--actor <actor>] -`,
+        purpose: "Create a Debt from flags or a Debt document on stdin.",
+        details: "The stdin document is YAML front matter (title, state, priority, needs, parent, supersedes, relates, note) followed by a Markdown body.",
+    },
+    show: {
+        arity: [1, Number.POSITIVE_INFINITY],
+        flags: COMMON,
+        usage: "debt show <DebtId>...",
+        purpose: "Read one or more Debts and their relationships.",
+    },
+    ls: {
+        arity: [0, 1],
+        flags: { ...COMMON, closed: "boolean", all: "boolean", world: "boolean", limit: "value" },
+        usage: "debt ls [<namespace-selector>] [--closed | --all] [--world] [--limit <n>]",
+        purpose: "List Debts in the selected namespace.",
+        details: [
+            "With no selector, lists the current directory Debt context.",
+            "debt/ selects the root namespace; --world lists every namespace in the current Debt world.",
+        ].join("\n"),
+    },
+    ready: {
+        arity: [0, 0],
+        flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" },
+        usage: "debt ready [--world] [--parent <DebtId>] [--limit <n>]",
+        purpose: "List open Debts whose every dependency is complete or dropped.",
+        details: "--world lists every namespace in the current Debt world.",
+    },
+    blocked: {
+        arity: [0, 0],
+        flags: { ...COMMON, world: "boolean", parent: "value", limit: "value" },
+        usage: "debt blocked [--world] [--parent <DebtId>] [--limit <n>]",
+        purpose: "List Debts with unmet dependencies.",
+        details: "--world lists every namespace in the current Debt world.",
+    },
+    query: {
+        arity: [0, 0],
+        flags: {
+            ...COMMON,
+            where: "value",
+            world: "boolean",
+            closed: "boolean",
+            all: "boolean",
+            sort: "value",
+            limit: "value",
+        },
+        usage: `debt query [--where <expression>] [--closed | --all] [--world]
+  [--sort priority|created|updated|id] [--limit <n>]`,
+        purpose: "Filter and sort Debts with a boolean expression.",
+        details: [
+            "fields: state priority title id parent under needs blocks ready blocked created updated",
+            "operators: = != < > <= >= ~ and or not ( )",
+            "sort: priority and created ascend; updated descends; id is lexical. Default: priority.",
+            "--world lists every namespace in the current Debt world.",
+            "By default only active Debts match; --closed selects terminal Debts, --all includes both.",
+            "examples:",
+            "  keiyaku debt query --where 'priority <= 1 and ready' --world",
+            "  keiyaku debt query --where 'updated < 2026-08-06T00:00:00.000Z' --world",
+        ].join("\n"),
+    },
+    tree: {
+        arity: [1, 1],
+        flags: COMMON,
+        usage: "debt tree <DebtId>",
+        purpose: "Show a Debt and its parent/child breakdown.",
+    },
+    doctor: {
+        arity: [0, 0],
+        flags: COMMON,
+        usage: "debt doctor",
+        purpose: "Check Debts for inconsistencies without changing them.",
+    },
+    update: {
+        arity: [1, 1],
+        flags: {
+            ...COMMON,
+            title: "value",
+            body: "value",
+            append: "value",
+            note: "value",
+            priority: "value",
+            needs: "repeat",
+            "drop-needs": "repeat",
+            parent: "value",
+            "no-parent": "boolean",
+            supersedes: "repeat",
+            "drop-supersedes": "repeat",
+            relates: "repeat",
+            "drop-relates": "repeat",
+        },
+        usage: `debt update <DebtId> [--title <text>] [--body <text>|- | --append <text>]
+  [--note <text>]
+  [--priority 0..3] [--needs <DebtId>]... [--drop-needs <DebtId>]...
+  [--parent <DebtId> | --no-parent]
+  [--supersedes <DebtId>]... [--drop-supersedes <DebtId>]...
+  [--relates <DebtId>]... [--drop-relates <DebtId>]...`,
+        purpose: "Change a Debt's fields and relationships.",
+        details: [
+            "--body replaces the body; --append adds text after it, separated by a newline when needed.",
+            "--body - reads replacement body text from stdin.",
+        ].join("\n"),
+    },
+    done: {
+        arity: [1, Number.POSITIVE_INFINITY],
+        flags: { ...COMMON, note: "value" },
+        usage: "debt done <DebtId>... [--note <text>]",
+        purpose: "Mark one or more Debts done.",
+    },
+    drop: {
+        arity: [1, Number.POSITIVE_INFINITY],
+        flags: { ...COMMON, note: "value" },
+        usage: "debt drop <DebtId>... [--note <text>]",
+        purpose: "Mark one or more Debts as no longer needed.",
+    },
+    context: {
+        arity: [0, 1],
+        flags: COMMON,
+        usage: "debt context [<namespace>]",
+        purpose: "Set or read the default Debt namespace for this directory.",
+        details: "Omit <namespace> to read the current context; use / to reset it to the root namespace.",
+    },
+};
+export function isDebtAction(value) {
+    return value !== undefined && Object.hasOwn(DEBT_COMMAND_SPECS, value);
+}
+export function renderDebtHelp(action) {
+    if (action !== undefined) {
+        const spec = DEBT_COMMAND_SPECS[action];
+        return `${spec.purpose}\n\n${renderDebtUsage(action)}${spec.details === undefined ? "" : `\n\n${spec.details}`}`;
+    }
+    const nameWidth = Math.max(...Object.keys(DEBT_COMMAND_SPECS).map((name) => name.length));
+    return [
+        "usage  keiyaku debt <command> ...",
+        "      keiyaku debt <command> --help   shows that command's complete usage",
+        "",
+        ...Object.entries(DEBT_COMMAND_SPECS).map(([name, spec]) => `  ${name.padEnd(nameWidth)}  ${spec.purpose}`),
+    ].join("\n");
+}
+function renderDebtUsage(action) {
+    return DEBT_COMMAND_SPECS[action].usage
+        .split("\n")
+        .map((line, index) => {
+        if (index === 0 || line.trimStart().startsWith("debt ")) {
+            const command = line.trimStart().startsWith("debt ") ? `keiyaku ${line.trim()}` : `keiyaku ${line}`;
+            return `${index === 0 ? "usage  " : "      "}${command}`;
+        }
+        return `      ${line.trim()}`;
+    })
+        .join("\n");
+}
+function debtUsage(action) {
+    const lines = DEBT_COMMAND_SPECS[action].usage.split("\n");
+    return lines
+        .map((line, index) => {
+        if (index === 0 || line.trimStart().startsWith("debt "))
+            return `keiyaku ${line.trim()}`;
+        return `           ${line.trim()}`;
+    })
+        .join("\n");
+}
+export function debtUsageGuide(action) {
+    return {
+        scope: `keiyaku debt ${action}`,
+        accepts: debtUsage(action),
+        help: `keiyaku debt ${action} --help`,
+    };
+}
+/** One scan spec per Debt action: `-` reads the document, or `--body -` replaces an update body. */
+function scanSpec(action, spec) {
+    return {
+        subject: `debt ${action}`,
+        flags: spec.flags,
+        ...(spec.stdin === undefined ? {} : { stdin: spec.stdin }),
+        stdinRefusal: "stdin marker '-' is not valid here",
+        ...(action === "update" ? { stdinValue: "body" } : {}),
+    };
+}
+function validateUpdate(scanned, fail) {
+    const flags = scanned.flags;
+    if (flags.body !== undefined && flags.append !== undefined)
+        fail("--body and --append are mutually exclusive");
+    if (flags.parent !== undefined && flags["no-parent"] === true)
+        fail("--parent and --no-parent are mutually exclusive");
+    if (Object.keys(flags).every((name) => name === "json"))
+        fail("debt update requires at least one patch option");
+}
+function validateDebtReadFlags(action, flags, fail) {
+    if ((action === "ls" || action === "query") && flags.closed === true && flags.all === true)
+        fail("--closed and --all are mutually exclusive");
+    if (action === "ls" && flags.world === true) {
+        // An explicit selector is checked below, after positional shape is known.
+    }
+    if (typeof flags.limit === "string") {
+        try {
+            validateDebtLimit(flags.limit);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    if (typeof flags.sort === "string" &&
+        flags.sort !== "priority" &&
+        flags.sort !== "created" &&
+        flags.sort !== "updated" &&
+        flags.sort !== "id") {
+        fail("--sort must be priority, created, updated, or id");
+    }
+    if ((action === "ready" || action === "blocked") && typeof flags.parent === "string") {
+        try {
+            validateDebtParent(flags.parent);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+/** Actions whose positionals are all addressed DebtIds validated by the native owner. */
+const DEBT_ID_ACTIONS = new Set(["show", "tree", "update", "done", "drop"]);
+/** Validate every addressed DebtId positional through the native owner before any read or write. */
+function validateDebtIdPositionals(positionals, fail) {
+    for (const debtId of positionals) {
+        try {
+            parseDebtId(debtId);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+}
+/** Validate an explicit `debt ls` namespace selector through the native owner. */
+function validateListSelector(selector, fail) {
+    if (selector !== "debt/" && (!selector.startsWith("debt/") || !selector.endsWith("/")))
+        fail(`invalid Debt namespace selector: ${selector}`);
+    if (selector === "debt/")
+        return;
+    try {
+        parseDebtNamespaceSelector(selector);
+    }
+    catch (error) {
+        fail(error instanceof Error ? error.message : String(error));
+    }
+}
+function validateDebtScan(action, scanned, fail) {
+    const spec = DEBT_COMMAND_SPECS[action], { positionals, flags, stdin } = scanned;
+    if (positionals.length < spec.arity[0])
+        fail(spec.arity[1] === 1 ? `debt ${action} requires a DebtId` : `debt ${action} requires at least one DebtId`);
+    if (positionals.length > spec.arity[1])
+        fail(spec.arity[1] === 0
+            ? `debt ${action} accepts no positional arguments`
+            : `debt ${action} accepts at most ${spec.arity[1]} positional argument${spec.arity[1] === 1 ? "" : "s"}`);
+    if (action === "add" && (stdin === "document") === (positionals.length === 1))
+        fail("debt add requires either TITLE or '-' input");
+    if (action === "add" &&
+        stdin === "document" &&
+        Object.keys(flags).some((name) => name !== "json" && name !== "namespace" && name !== "actor"))
+        fail("debt add document input owns its creation fields");
+    if (DEBT_ID_ACTIONS.has(action))
+        validateDebtIdPositionals(positionals, fail);
+    if (action === "ls" && positionals.length === 1) {
+        validateListSelector(positionals[0], fail);
+        if (flags.world === true)
+            fail("--world cannot be combined with an explicit Debt namespace selector");
+    }
+    validateDebtReadFlags(action, flags, fail);
+    if (action === "update")
+        validateUpdate(scanned, fail);
+}
+export function parseDebtCommand(argv) {
+    const candidate = argv[0];
+    if (!isDebtAction(candidate)) {
+        throw new CliUsageError(`unknown debt command: ${candidate ?? ""}`, unknownCommandGuide(DEBT_FAMILY_USAGE_GUIDE, candidate ?? ""));
+    }
+    const action = candidate;
+    const fail = (message) => {
+        throw new CliUsageError(message, debtUsageGuide(action));
+    };
+    const scanned = scanArgs(argv, scanSpec(action, DEBT_COMMAND_SPECS[action]), fail);
+    validateDebtScan(action, scanned, fail);
+    let where;
+    if (action === "query" && typeof scanned.flags.where === "string") {
+        try {
+            where = parseDebtQueryExpression(scanned.flags.where);
+        }
+        catch (error) {
+            fail(error instanceof Error ? error.message : String(error));
+        }
+    }
+    return {
+        command: "debt",
+        action,
+        output: scanned.flags.json === true ? "json" : "text",
+        ...scanned,
+        ...(where === undefined ? {} : { where }),
+    };
+}

package/build/src/cli/commands/debt-query.d.ts

@@ -0,0 +1,5 @@
+import { type DebtQueryExpression } from "../../debt/query.js";
+export type { DebtQueryExpression } from "../../debt/query.js";
+export declare function parseDebtQueryExpression(source: string): DebtQueryExpression;
+export declare function validateDebtLimit(source: string): void;
+export declare function validateDebtParent(source: string): void;

package/build/src/cli/commands/{task-query.js → debt-query.js}

@@ -1,4 +1,4 @@
-import { normalizeTaskQueryPredicate, TaskQueryPredicateError, } from "../../task/query.js";
+import { normalizeDebtQueryPredicate, DebtQueryPredicateError, } from "../../debt/query.js";
 function syntax(message, offset) {
     throw new Error(`${message} at column ${offset + 1}`);
 }
@@ -84,7 +84,7 @@ function parsedPredicate(field, operator, value) {
     if (field.value === "title" && value.kind !== "string") {
         syntax("title values must use double quotes", value.offset);
     }
-    // Acquire textual literals only; the Task owner judges fields, operators and values.
+    // Acquire textual literals only; the Debt owner judges fields, operators and values.
     const literal = field.value === "priority"
         ? Number(value.value)
         : field.value === "parent" && value.value === "none"
@@ -93,10 +93,10 @@ function parsedPredicate(field, operator, value) {
                 ? value.value === "true"
                 : value.value;
     try {
-        return normalizeTaskQueryPredicate({ field: field.value, operator: operator.value, value: literal });
+        return normalizeDebtQueryPredicate({ field: field.value, operator: operator.value, value: literal });
     }
     catch (error) {
-        if (error instanceof TaskQueryPredicateError) {
+        if (error instanceof DebtQueryPredicateError) {
             return syntax(error.message, { field, operator, value }[error.part].offset);
         }
         throw error;
@@ -175,20 +175,20 @@ class Parser {
         return parsedPredicate(field, operator, value);
     }
 }
-export function parseTaskQueryExpression(source) {
+export function parseDebtQueryExpression(source) {
     if (source.trim().length === 0)
         return syntax("query expression must be nonblank", 0);
     return new Parser(lex(source)).parse();
 }
-export function validateTaskLimit(source) {
+export function validateDebtLimit(source) {
     if (!/^[1-9][0-9]*$/u.test(source) || !Number.isSafeInteger(Number(source)))
         throw new Error("--limit requires a positive safe integer");
 }
-export function validateTaskParent(source) {
+export function validateDebtParent(source) {
     try {
-        normalizeTaskQueryPredicate({ field: "under", operator: "=", value: source });
+        normalizeDebtQueryPredicate({ field: "under", operator: "=", value: source });
     }
     catch {
-        throw new Error("--parent requires a canonical TaskId");
+        throw new Error("--parent requires a canonical DebtId");
     }
 }

package/build/src/cli/commands/{task.d.ts → debt.d.ts}

@@ -1,4 +1,4 @@
-import type { ParsedTaskCommand } from "./task-grammar.js";
+import type { ParsedDebtCommand } from "./debt-grammar.js";
 import type { CliRuntime } from "../runtime.js";
 import type { CliCoordinates } from "../coordinates.js";
-export declare function runTaskCommand(command: ParsedTaskCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<number>;
+export declare function runDebtCommand(command: ParsedDebtCommand, coordinates: CliCoordinates, runtime: CliRuntime): Promise<number>;