halfcycle 0.4.5 → 0.4.7

package/dist/open-phase.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"open-phase.d.ts","sourceRoot":"","sources":["../src/open-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAIL,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAY3B;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qDAAqD;IACrD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,yEAAyE;QACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;CACH;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,eAAe,GAAG,UAAU,CAAC,GAAG,MAAM,CAUtG;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,MAAM;aAEd,OAAO,EAAE,MAAM,GAAG,IAAI;aACtB,aAAa,EAAE,MAAM,GAAG,IAAI;gBAH5B,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAKtD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,kFAItB,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA4BhB;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,IAAI,CAAC,EAAE,MAAM,GACZ,iBAAiB,GAAG,IAAI,CAmB1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,CAAC,CA0EtB"}
+{"version":3,"file":"open-phase.d.ts","sourceRoot":"","sources":["../src/open-phase.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AAIH,OAAO,EAKL,KAAK,YAAY,EACjB,KAAK,kBAAkB,EACxB,MAAM,mBAAmB,CAAC;AAY3B;;;;;;;;GAQG;AACH,MAAM,WAAW,iBAAiB;IAChC,wEAAwE;IACxE,IAAI,EAAE,MAAM,CAAC;IACb,iEAAiE;IACjE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,sFAAsF;AACtF,MAAM,WAAW,WAAW;IAC1B,iDAAiD;IACjD,KAAK,EAAE,MAAM,GAAG,IAAI,CAAC;IACrB,qDAAqD;IACrD,aAAa,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B;;;;OAIG;IACH,YAAY,EAAE,iBAAiB,GAAG,IAAI,CAAC;IACvC,QAAQ,EAAE;QACR,UAAU,EAAE,MAAM,CAAC;QACnB,QAAQ,EAAE,MAAM,CAAC;QACjB,KAAK,EAAE,MAAM,CAAC;QACd,aAAa,EAAE,MAAM,CAAC;QACtB,yEAAyE;QACzE,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;QAC/B,SAAS,EAAE,MAAM,CAAC;KACnB,CAAC;IACF;;;;;OAKG;IACH,aAAa,EAAE,YAAY,GAAG,IAAI,CAAC;CACpC;AAcD;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,WAAW,EAAE,OAAO,GAAG,eAAe,GAAG,UAAU,CAAC,GAAG,MAAM,CAUtG;AAED;;;;;;;;;;;;;;GAcG;AACH,qBAAa,gBAAiB,SAAQ,KAAK;aAEvB,MAAM,EAAE,MAAM;aAEd,OAAO,EAAE,MAAM,GAAG,IAAI;aACtB,aAAa,EAAE,MAAM,GAAG,IAAI;gBAH5B,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,OAAO,EAAE,MAAM,GAAG,IAAI,EACtB,aAAa,GAAE,MAAM,GAAG,IAAW;CAKtD;AAED;;;;;GAKG;AACH,eAAO,MAAM,mBAAmB,kFAItB,CAAC;AAEX,MAAM,WAAW,cAAc;IAC7B,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,kBAAkB,CAChC,QAAQ,EAAE,MAAM,EAChB,GAAG,GAAE,MAAM,CAAC,UAAwB,EACpC,IAAI,CAAC,EAAE,MAAM,GACZ,cAAc,CA4BhB;AAuBD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAgB,eAAe,CAC7B,YAAY,EAAE,MAAM,EACpB,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,IAAI,CAAC,EAAE,MAAM,GACZ,iBAAiB,GAAG,IAAI,CAmB1B;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAsB,SAAS,CAC7B,UAAU,EAAE,cAAc,EAC1B,KAAK,EAAE,MAAM,GAAG,IAAI,EACpB,KAAK,EAAE,kBAAkB,EACzB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,WAAW,CAAC,CA6EtB"}

package/dist/plan.d.ts

@@ -0,0 +1,200 @@
+/**
+ * The client half of `npx halfcycle@latest plan <phase> [--show]` (System view · E2,
+ * feature `phase-plan-and-scope-approval`, AC2): check the project's description and the
+ * phase's plan file on the machine, report the description, then report the plan bound
+ * to that description version; with `--show`, list every part to the person and record
+ * on this machine which phase, number and plan version were shown.
+ *
+ * THE ORDER IS THE SPEC'S. (1) the description stage, `checkAndReportDescription`
+ * (`./system-report.ts`), never a copy of it; (2) the plan is read and checked in that
+ * stage's `beforeSend`, which runs after the description passed and before the
+ * credential is read or anything sent, so a bad plan sends nothing, the description
+ * included; (3) the plan that was checked is the plan sent, never a second read of the
+ * file; (4) with `--show`, the list is printed and the shown record written.
+ *
+ * ONE HOME FOR EVERY RULE THIS VERB APPLIES (INV-003). The plan's shape and its check
+ * against a description are `@halfcycle/events`' `checkPhasePlan`; the route's request
+ * and answer are its `phasePlanRequestSchema` and `phasePlanResultSchema`. The plan
+ * file's name is `renderPhaseSegment`'s (INV-023), and "is the file's phase the phase
+ * asked for" compares the two segments it renders, because that function is where a
+ * number and its decimal string become one phase. The shown record's format is
+ * `@halfcycle/core`'s `serialiseShownPlans` and `parseShownPlans`; this module keeps
+ * only the I/O. Whether a typed number reaches this phase is `resolvePhaseReference`
+ * (`@halfcycle/core`). The two approval-line swaps take their sentences and the floor
+ * from `client-version.ts` (`@halfcycle/events`); the switched-off swap is decided by
+ * the server's `typedApprovalOffered`, never by the client's copy of the switch, and
+ * delivery's `clientOffersChatApproval` is never called here. "Is this a service
+ * without the route" is `isMissingRoute`.
+ *
+ * THE CHANGE WORDS are the system picture's `PART_STATES` labels for `padd`, `pchg`
+ * and `pdel`, repeated in `PLAN_CHANGE_LABELS` because this package may not import the
+ * picture package (INV-001). `test/plan-verb.test.ts` reads that package's source and
+ * holds the two equal.
+ *
+ * WHAT LEAVES THE MACHINE. The checked description (through the shared stage), then
+ * `{ descriptionVersion, plan }`. Nothing is written into the person's tree; the shown
+ * record is machine state under the home folder (INV-019).
+ *
+ * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and `@halfcycle/core`
+ * only. SHIPS TO CLIENT DISK inside the CLI: every string here is a sentence a person
+ * reads, so none names an internal register, route or setting; no comment sits beside
+ * an object member.
+ */
+import { type PhasePlan, type PhasePlanChange, type PhasePlanProblem, type PlannedScopeState, type SystemDescription } from '@halfcycle/events';
+import { type ShownPlanEntry } from '@halfcycle/core';
+import type { RepoCredential } from './open-phase.js';
+import { type DescriptionVerb, type SystemDeps, type SystemRun } from './system-report.js';
+/** The usage line, printed for no phase, an extra argument or an unknown flag. */
+export declare const PLAN_USAGE = "npx halfcycle@latest plan <phase> [--show] [--repo <root>]";
+/** The folder the plan file sits in, relative to the repository root. */
+export declare const PLAN_DIR_REL = "docs/phases";
+/**
+ * The plan file for `phase`, relative to the repository root:
+ * `docs/phases/<segment>.plan.json`, the segment being `renderPhaseSegment`'s and no
+ * other. Throws on a phase that is not a valid identity, as that function does.
+ */
+export declare function planFileRel(phase: string | number): string;
+/**
+ * The words for each change, as the system picture labels them (`PART_STATES`' `padd`,
+ * `pchg` and `pdel`). A test holds them equal to that package's source.
+ */
+export declare const PLAN_CHANGE_LABELS: Readonly<Record<PhasePlanChange, string>>;
+/**
+ * What the arguments after `plan` came to. Exactly one positional (the phase), at most
+ * one `--show` and at most one `--repo <root>`; anything else, no phase included, is
+ * usage.
+ */
+export type PlanArgs = {
+    ok: true;
+    phase: string;
+    show: boolean;
+    repoRoot: string | undefined;
+} | {
+    ok: false;
+};
+export declare function parsePlanArgs(argv: readonly string[]): PlanArgs;
+/** One line per plan problem, each naming where it is. */
+export declare function planProblemLines(raw: unknown, fileRel: string, problems: readonly PhasePlanProblem[]): string;
+/** What reading and checking the plan file came to: the checked plan, or the line to print. */
+export type PlanFileCheck = {
+    ok: true;
+    plan: PhasePlan;
+} | {
+    ok: false;
+    line: string;
+};
+/**
+ * Read `docs/phases/<segment>.plan.json` under `repoRoot` and check it against the
+ * checked `description`. Never throws. `phase` must already be a valid identity.
+ *
+ * In order: a missing file names the path and the remedy; a file that cannot be read,
+ * or is not JSON, says so (the parser's own sentence for the second); a plan naming a
+ * valid phase other than `phase` is refused naming both, before its other problems,
+ * because it is the wrong file; otherwise every problem `checkPhasePlan` finds. Each
+ * line says nothing was sent, because nothing is.
+ */
+export declare function readAndCheckPlan(repoRoot: string, phase: string, description: SystemDescription, verb: DescriptionVerb): PlanFileCheck;
+/**
+ * What came of reporting the plan. `recorded`: the service's answer, as its schema
+ * parsed it. `refused`: the service's own problems. `no-route`: this service cannot
+ * take a plan yet. `unavailable`: it could not be reported, and `why` says so.
+ */
+export type PlanOutcome = {
+    kind: 'recorded';
+    version: number;
+    phaseNumber: number;
+    state: PlannedScopeState;
+    changedParts: readonly string[];
+    typedApprovalOffered: boolean;
+} | {
+    kind: 'refused';
+    problems: PhasePlanProblem[];
+} | {
+    kind: 'no-route';
+} | {
+    kind: 'unavailable';
+    why: string;
+};
+/** The address the plan is reported to: the engagement and the phase are each one path segment, encoded once. */
+export declare function planReportUrl(credential: RepoCredential, phase: string | number): string;
+/**
+ * Report a checked plan bound to `descriptionVersion`. Never throws.
+ *
+ * One response-handling rule, the description report's: a body that parses under
+ * `phasePlanResultSchema` is authoritative whatever its status; otherwise the
+ * service's missing-route answer means it predates plans; anything else is reported
+ * by its status and the service's own sentence.
+ */
+export declare function reportPhasePlan(credential: RepoCredential, plan: PhasePlan, descriptionVersion: number): Promise<PlanOutcome>;
+/** What writing the shown record came to: on success, every entry the record now holds. */
+export type ShownWrite = {
+    ok: true;
+    entries: readonly ShownPlanEntry[];
+} | {
+    ok: false;
+};
+/**
+ * Record on this machine that `entry` was shown: `~/.halfcycle/engagements/<id>/`
+ * `shown-plans.json`, the directory composed by `engagementStateDir` (which checks the
+ * id) and the filename `SHOWN_PLANS_FILENAME`. Never throws.
+ *
+ * The record keeps the latest entry per phase, so the entry for this phase is
+ * replaced. An entry holding this number under another phase is dropped too: the
+ * service gives each phase one number and never changes it, so such an entry is
+ * stale, and `serialiseShownPlans` refuses two entries with one number, which would
+ * otherwise fail every later write. A missing or malformed record reads as nothing
+ * shown (`parseShownPlans`).
+ *
+ * Written to a temporary file in the same folder, mode `0600` set on it before the
+ * rename (a rename carries the source's bits), then renamed into place, so a reader
+ * sees the old record or the new one and never a part of one. `chmod` is skipped on
+ * Windows, where the bits mean nothing.
+ */
+export declare function writeShownPlan(engagementId: string, entry: ShownPlanEntry, home?: string): ShownWrite;
+/**
+ * The installed Halfcycle's version, as the project's `.halfcycle/bundle.json` holds
+ * it, or `undefined` when there is no pin, it cannot be read, or it holds no string
+ * version. The floor treats `undefined` as older than every release.
+ */
+export declare function readPinnedClientVersion(repoRoot: string): string | undefined;
+/**
+ * The line for a plan the service refused, as `plan` prints it, prefixed by the verb
+ * that is running. `draw phase` prints a refusal through this too, so the two verbs
+ * word it one way.
+ */
+export declare function planRefusedLines(verb: DescriptionVerb, phase: string, plan: PhasePlan, problems: readonly PhasePlanProblem[]): string;
+/**
+ * The line for a phase name `isValidPhaseIdentity` refuses, prefixed by the verb that
+ * is running. Nothing has been sent when it is printed.
+ */
+export declare function notAPhaseNameLine(verb: DescriptionVerb, phase: string): string;
+/** The pieces `runPlan` reaches outside itself through; replaced in tests. */
+export interface PlanDeps extends SystemDeps {
+    readonly reportPlan: (credential: RepoCredential, plan: PhasePlan, descriptionVersion: number) => Promise<PlanOutcome>;
+    readonly pinnedClientVersion: (repoRoot: string) => string | undefined;
+    readonly recordShown: (engagementId: string, entry: ShownPlanEntry) => ShownWrite;
+    readonly now: () => Date;
+}
+/** The sentence for the phase's state after the plan was recorded. */
+export declare function planStateSentence(state: PlannedScopeState): string;
+/**
+ * The line saying how the owner approves, with its two swaps (AC2). The server's
+ * `typedApprovalOffered: false` gives the switched-off sentence, whatever the client;
+ * otherwise a pinned version below the floor (none included) gives the update
+ * sentence; otherwise the typing offer.
+ *
+ * The offer names the phase, and its number too when typing the number would reach
+ * this phase among the phases shown on this machine (`resolvePhaseReference`): a
+ * phase whose name is that number would otherwise take it.
+ */
+export declare function approvalLine(phase: string, number: number, typedApprovalOffered: boolean, pinnedVersion: string | undefined, shown: readonly ShownPlanEntry[]): string;
+/** One line per change, in plan order: the part's name, what changes, the plan's line, and the changed mark. */
+export declare function changeLines(plan: PhasePlan, description: SystemDescription, changed: readonly string[]): string;
+/**
+ * The whole verb, in the order the module header gives. Exit 0 only when the plan is
+ * recorded and, with `--show`, the shown record is written. When that write fails the
+ * list is still printed, but not the approval line: an approval typed for a list this
+ * machine did not record could not bind to it, so the verb does not invite one.
+ */
+export declare function runPlan(repoRoot: string, phase: string, show: boolean, deps: PlanDeps): Promise<SystemRun>;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

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

package/dist/system-report.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The client half of `npx halfcycle@latest system` (System view · E1, feature
+ * `system-description`): read the project's `docs/system.json`, check it with the one
+ * shared check, warn about owned patterns that match no tracked file, and report it
+ * to the Halfcycle service, which answers with the version it holds.
+ *
+ * ONE HOME FOR EVERY RULE THIS VERB APPLIES (INV-003). The shape, the cross-field
+ * rules and the ownership grammar are `@halfcycle/events`' `checkSystemDescription`
+ * and `ownerOf` — this module calls them and restates none of them. The unowned-
+ * pattern warning asks `ownerOf` of a one-part, one-pattern description per pattern
+ * rather than matching paths itself, so "does this pattern own this file" has exactly
+ * one implementation, the one E3's counting uses. The answer's shape is the events
+ * package's `systemReportResultSchema`. "Is this a service without the route" is
+ * `isMissingRoute` (`./missing-route.ts`), shared with `build-record` and `draw`.
+ * `draw` and `plan` take this module's first stage, `checkAndReportDescription`,
+ * whole: the verbs read, check and report the description by one path, not copies.
+ *
+ * ONE RESPONSE-HANDLING RULE, the Build Record path's. A body that parses under
+ * `systemReportResultSchema` is authoritative, whatever its status. Otherwise the
+ * service's missing-route answer to a POST means it predates the route; anything
+ * else is reported by its status and the service's own sentence.
+ *
+ * WHAT LEAVES THE MACHINE. Only the description, and only after it passed the check.
+ * The tracked-file list read for the warning is a local read: nothing it finds is
+ * sent, and it sets nothing (INV-021). Nothing here writes into the person's tree.
+ *
+ * INV-001: Node builtins, the global `fetch`, `@halfcycle/events` and
+ * `@halfcycle/core` (through the shared credential and command helpers) only.
+ * SHIPS TO CLIENT DISK inside the CLI: every string here is a sentence a person
+ * reads, so none names an internal register, route or setting; no comment sits
+ * beside an object member.
+ */
+import { type SystemDescription, type SystemDescriptionProblem } from '@halfcycle/events';
+import type { RepoCredential } from './open-phase.js';
+/** Where the description lives, relative to the repository root. */
+export declare const SYSTEM_DESCRIPTION_REL = "docs/system.json";
+/**
+ * What reading `docs/system.json` came to. `missing`: there is no such file.
+ * `unreadable`: something is there and could not be read as a file. `not-json`: it
+ * was read and does not parse; `error` is the parser's own sentence. `read`: the
+ * parsed value, not yet checked.
+ */
+export type DescriptionFile = {
+    kind: 'missing';
+} | {
+    kind: 'unreadable';
+} | {
+    kind: 'not-json';
+    error: string;
+} | {
+    kind: 'read';
+    value: unknown;
+};
+/**
+ * Read and parse the description under `repoRoot`. Never throws. A missing file is
+ * told apart from an unreadable one because the remedies differ: the first is
+ * written by the method's architecture step, the second is the person's to fix.
+ */
+export declare function readDescriptionFile(repoRoot: string): DescriptionFile;
+/**
+ * A problem's place in words a person can find in their file: the dotted path the
+ * check reports (`parts.3.name`), then the part or connection it is in, named by its
+ * id or its ends when the raw value carries them, by its position otherwise.
+ */
+export declare function problemPlace(raw: unknown, path: string): string;
+/** One line per problem, each naming where it is, for the terminal. */
+export declare function problemLines(raw: unknown, problems: readonly SystemDescriptionProblem[]): string;
+/** An owned pattern that matches no file git tracks, and the part that lists it. */
+export interface UnownedPattern {
+    readonly partId: string;
+    readonly pattern: string;
+}
+/** How the tracked-file list is obtained; replaced in tests. `null` when there is none. */
+export type ListTrackedFiles = (repoRoot: string) => string[] | null;
+/**
+ * The files git tracks under `repoRoot`, as `git ls-files -z` prints them (relative,
+ * `/`-separated, unquoted), or `null` when there is no git, `repoRoot` is not inside
+ * a repository, or the list could not be read. The repository-locating variables are
+ * removed from git's environment so the folder named is the one read.
+ */
+export declare const listTrackedFiles: ListTrackedFiles;
+/**
+ * The owned patterns that match no tracked file — how a description drifts from the
+ * code. A warning, never a refusal. `null` when the tracked-file list is unavailable:
+ * the warning is then skipped, not guessed.
+ *
+ * Each pattern is asked of `ownerOf` on its own (a description holding just that part
+ * with just that pattern), so a pattern another part outranks on every file still
+ * counts as matching: the warning is about patterns that name nothing, not about
+ * ranking.
+ */
+export declare function unownedPatterns(description: SystemDescription, tracked: readonly string[] | null): UnownedPattern[] | null;
+/**
+ * The warning lines for unowned patterns, one per pattern, each prefixed by the verb
+ * that is running (`draw`, `plan` or `system`), as every other line it prints is.
+ */
+export declare function unownedPatternLines(unowned: readonly UnownedPattern[], verb: DescriptionVerb): string;
+/**
+ * What came of reporting the description. `recorded`: the service holds it as
+ * `version` (a description it already had returns that version). `refused`: the
+ * service's own problems. `no-route`: this service cannot take a description yet.
+ * `unavailable`: it could not be reported, and `why` says so.
+ */
+export type ReportOutcome = {
+    kind: 'recorded';
+    version: number;
+    reportedAt: string;
+} | {
+    kind: 'refused';
+    problems: SystemDescriptionProblem[];
+} | {
+    kind: 'no-route';
+} | {
+    kind: 'unavailable';
+    why: string;
+};
+/** The address the description is reported to: the engagement is one path segment, encoded once. */
+export declare function systemReportUrl(credential: RepoCredential): string;
+/**
+ * Report a checked description. Never throws: the network, the service and an answer
+ * this CLI cannot read are each an outcome the caller prints.
+ */
+export declare function reportSystemDescription(credential: RepoCredential, description: SystemDescription): Promise<ReportOutcome>;
+/** What `system` prints and the exit code it ends with. */
+export interface SystemRun {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exitCode: 0 | 1;
+}
+/** The pieces `runSystem` reaches outside itself through; replaced in tests. */
+export interface SystemDeps {
+    readonly readCredential: (repoRoot: string) => RepoCredential;
+    readonly listTracked: ListTrackedFiles;
+    readonly report: (credential: RepoCredential, description: SystemDescription) => Promise<ReportOutcome>;
+}
+/**
+ * What the shared first stage came to. `stopped`: the verb ends here and `stderr` is
+ * the whole of what it prints. `no-route`: the service cannot take a description yet;
+ * the caller words that for its own verb. `recorded`: the service holds the checked
+ * description as `version`, and `credential` is the one it was reported with.
+ * `warnings` is the unowned-pattern lines, printed whatever the caller does next.
+ */
+export type DescriptionStage = {
+    kind: 'stopped';
+    stderr: string;
+} | {
+    kind: 'no-route';
+    warnings: string;
+} | {
+    kind: 'recorded';
+    version: number;
+    credential: RepoCredential;
+    warnings: string;
+};
+/** The verbs that report the description first. Names the prefix of every line. */
+export type DescriptionVerb = 'system' | 'draw' | 'plan';
+/**
+ * A verb's own local refusal, asked with the description that just passed the check:
+ * the line to print, or `null` to go on. `plan` checks its plan file against that
+ * description here; `draw` ignores the argument.
+ */
+export type BeforeSend = (description: SystemDescription) => string | null;
+/**
+ * READ, CHECK, WARN, REPORT — the one path `system`, `draw` and `plan` take before
+ * anything else (feature `diagram-files-for-docs`, step 1 and 2 of the command). The
+ * order is the spec's: nothing is sent unless the file reads, parses and passes every
+ * rule, and the credential is only looked for once there is something to send.
+ *
+ * `beforeSend` is the caller's own local refusal, asked after the description passed
+ * and before the credential is read or anything sent: `draw` refuses there when a file
+ * it does not own is in the way, and `plan` when its plan file is missing, unreadable or
+ * fails `checkPhasePlan` against the checked description it is handed, so a refusal it
+ * can make on the machine never costs a request (the description included). It returns
+ * the line to print, or `null` to go on.
+ */
+export declare function checkAndReportDescription(repoRoot: string, deps: SystemDeps, verb: DescriptionVerb, beforeSend?: BeforeSend): Promise<DescriptionStage>;
+/** The whole `system` verb: the shared stage, then its version printed. */
+export declare function runSystem(repoRoot: string, deps: SystemDeps): Promise<SystemRun>;
+//# sourceMappingURL=system-report.d.ts.map

package/dist/system-report.d.ts.map

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "halfcycle",
-  "version": "0.4.5",
+  "version": "0.4.7",
   "description": "Your coding agents are the engineers. Halfcycle is the rest of the team: product owner, architect, planner and independent reviewer for Claude Code.",
   "keywords": [
     "claude",