halfcycle 0.4.5 → 0.4.6

package/dist/system-report.d.ts

@@ -0,0 +1,168 @@
+/**
+ * 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` takes this module's first stage, `checkAndReportDescription`, whole: the
+ * two verbs read, check and report the description by one path, not two 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. */
+export declare function unownedPatternLines(unowned: readonly UnownedPattern[]): 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';
+/**
+ * READ, CHECK, WARN, REPORT — the one path both `system` and `draw` 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, so a refusal it can make on the machine never costs a
+ * request. It returns the line to print, or `null` to go on.
+ */
+export declare function checkAndReportDescription(repoRoot: string, deps: SystemDeps, verb: DescriptionVerb, beforeSend?: () => string | null): 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.6",
   "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",