hafez 1.3.0 → 2.0.0

package/dist/surfaces/items.d.ts

@@ -0,0 +1,366 @@
+import { type DocTarget, type WriteLineField } from '../contracts.js';
+import { renderActionHandles } from '../document.js';
+import type { ActionAge } from '../stale.js';
+import type { KnowledgeSubtype, UpdateFields, UpdateResult } from '../types.js';
+import { type OnboardHarness } from '../harness.js';
+import type { Mode } from '../cli/install.js';
+/** Every Surface the contract names. The static ones are composed in
+ * surfaces.ts; the binary ones are command output, rendered at run time. */
+export type SurfaceId = 'block' | 'hafezSkillDescription' | 'hafezSkillBody' | 'hafezSaveDescription' | 'hafezSaveBody' | 'read' | 'readHeader' | 'readFooter' | 'readMiss' | 'updateSuccess' | 'updateMisuse' | 'createKnowledge' | 'digestError' | 'batchMisuse' | 'mechanised' | 'schema' | 'onboard';
+/** Places another Item inside this one's text, counted against the same Surface. */
+export type Place = (id: string) => string;
+export interface Item {
+    /** The Item's row text in the owner table. */
+    label: string;
+    owner: SurfaceId;
+    /** A declared second placement, for agents whose Owner is absent. */
+    fallback?: SurfaceId;
+    /** The owner table's Invoke-only column. */
+    invokeOnly: string;
+    /** The audit row, field count or ticket that earns the Item its place. */
+    evidence: string;
+    /** Static text. A function form may place nested Items, and may give the
+     * fallback a shorter form than the Owner. */
+    text?: string | ((place: Place, at: 'owner' | 'fallback') => string);
+    /** What the binary computes: for Items owned by command output, and for a
+     * static Item a binary Surface places filled in (the create line in the
+     * `read` miss). */
+    render?: (input: never) => string;
+}
+/** An existing note a Near-match names. */
+export interface NearMatchNote {
+    slug: string;
+    name: string;
+    description?: string | null;
+    subtype: KnowledgeSubtype;
+}
+/** An entity matching the working folder, as `onboard --block` names it. */
+export interface FolderMatch {
+    slug: string;
+    description: string | null;
+}
+/** The three outputs of the Near-match Item: the `create knowledge` refusal
+ * (the message the error line carries), the relate line printed after a
+ * written note's slug, and `batch`'s warning line. */
+export type NearMatchRender = {
+    form: 'refusal';
+    name: string;
+    /** The flags the create was given, in order: `[flag]` for a switch. */
+    flags: [flag: string, value?: string][];
+    /** The text passed as `--synthesis`, offered as evidence. */
+    evidence?: string;
+    matches: NearMatchNote[];
+} | {
+    form: 'relate';
+    slug: string;
+    related: string[];
+    resembles: string[];
+} | {
+    form: 'batchWarning';
+    index: number;
+    name: string;
+    matches: string[];
+};
+declare function renderNearMatch(input: NearMatchRender): string;
+/** What a `read` Footer is rendered from: the file it ends. */
+export interface FooterInput {
+    slug: string;
+    target: DocTarget;
+    /** The first open action's Handle; absent when no action is open. */
+    handle?: string;
+    /** Who the session log entry names: detected from the Harness. */
+    agent: string;
+}
+/** The Footer's op as the batch object carries it: what `read --json` puts
+ * under `writes`, and what the Write Line renders. */
+export type FooterOp = {
+    op: 'update';
+    slug: string;
+    fields: Partial<Record<WriteLineField, unknown>>;
+} | {
+    op: 'promote';
+    slug: string;
+    target: string;
+};
+export declare function footerOp(input: FooterInput): FooterOp;
+/** The Footer: a blank line, a rule line, plain prose and one fenced block. */
+declare function renderFooter(input: FooterInput): string;
+/** `Updated <slug>: <what changed>.` — one phrase per change, nothing else. */
+declare function renderUpdateSummary({ slug, fields, result }: {
+    slug: string;
+    fields: UpdateFields;
+    result: UpdateResult;
+}): string;
+/** The suffix a Stale open line carries on `read`: its age, or that it is
+ * undated. A fresh line carries none. */
+declare function renderStaleMarker({ stale, age_days }: ActionAge): string;
+/** The line after an update's success while Stale lines remain on the entity. */
+declare function renderStaleReminder({ handles }: {
+    handles: string[];
+}): string;
+/** What a misuse retries from: the file's Footer, or the `read` miss when the
+ * slug names no file. */
+export type MisuseRetry = {
+    footer: FooterInput;
+} | {
+    miss: {
+        slug: string;
+        closest: string[];
+    };
+};
+/** The error line stating nothing was written, any detail lines, then the
+ * Footer (which brings its own blank line) or, after a blank line, the miss. */
+declare function renderUpdateMisuse(input: {
+    error: string;
+    details?: string[];
+} & MisuseRetry): string;
+/** Step 3 of the onboard script: the exact entries that let `hafez` run and
+ * write the vault without a prompt. Claude Code runs it from an allow entry;
+ * Codex from a command rule, with the vault a writable root of the sandbox. */
+declare function renderHarnessPermissions({ harness, vault }: {
+    harness: OnboardHarness;
+    vault: string;
+}): string;
+/** The four lines said to the user at hand-over, or line 2 alone. Line 1
+ * carries the save keystroke of the Harness `onboard` ran in; line 2 is the
+ * Mode. */
+declare function renderTeachingLines({ harness, mode, line2Only }: {
+    harness: OnboardHarness;
+    mode: Mode;
+    line2Only?: boolean;
+}): string;
+export declare const ITEMS: {
+    loadTriggers: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    slugMissRecovery: {
+        label: string;
+        owner: "readMiss";
+        invokeOnly: string;
+        evidence: string;
+        render: ({ slug, closest }: {
+            slug: string;
+            closest: string[];
+        }) => string;
+    };
+    parentDescription: {
+        label: string;
+        owner: "readHeader";
+        invokeOnly: string;
+        evidence: string;
+        /** The `parent:` line's value: the slug, with the parent's description
+         * in brackets when it has one. */
+        render: ({ slug, description }: {
+            slug: string;
+            description: string | null;
+        }) => string;
+    };
+    writeTriggers: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: (place: Place) => string;
+    };
+    knowledgeBoundary: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    neverAsk: {
+        label: string;
+        owner: "block";
+        fallback: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: (_place: Place, at: "owner" | "fallback") => string;
+    };
+    readBeforeWrite: {
+        label: string;
+        owner: "block";
+        fallback: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    oneCommand: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    openActions: {
+        label: string;
+        owner: "block";
+        fallback: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    neverEditByHand: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    neverSaveUnprompted: {
+        label: string;
+        owner: "block";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    createLines: {
+        label: string;
+        owner: "block";
+        fallback: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+        /** The entity create line for one name: what the `read` miss places. */
+        render: (name: string) => string;
+    };
+    writeLine: {
+        label: string;
+        owner: "readFooter";
+        fallback: "updateMisuse";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderFooter;
+    };
+    handles: {
+        label: string;
+        owner: "read";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderActionHandles;
+    };
+    staleMarker: {
+        label: string;
+        owner: "read";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderStaleMarker;
+    };
+    staleReminder: {
+        label: string;
+        owner: "updateSuccess";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderStaleReminder;
+    };
+    updateSummary: {
+        label: string;
+        owner: "updateSuccess";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderUpdateSummary;
+    };
+    updateMisuse: {
+        label: string;
+        owner: "updateMisuse";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderUpdateMisuse;
+    };
+    sessionLogOnUpdate: {
+        label: string;
+        owner: "mechanised";
+        invokeOnly: string;
+        evidence: string;
+    };
+    nearMatch: {
+        label: string;
+        owner: "createKnowledge";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderNearMatch;
+    };
+    saveTrigger: {
+        label: string;
+        owner: "hafezSaveDescription";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    saveMechanics: {
+        label: string;
+        owner: "hafezSaveBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    unknownSlugAtSave: {
+        label: string;
+        owner: "digestError";
+        invokeOnly: string;
+        evidence: string;
+        render: (slugs: readonly string[]) => string;
+    };
+    find: {
+        label: string;
+        owner: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    rareOps: {
+        label: string;
+        owner: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    batchShape: {
+        label: string;
+        owner: "hafezSkillBody";
+        fallback: "batchMisuse";
+        invokeOnly: string;
+        evidence: string;
+        text: (_place: Place, at: "owner" | "fallback") => string;
+    };
+    upgradeReconfigure: {
+        label: string;
+        owner: "hafezSkillBody";
+        invokeOnly: string;
+        evidence: string;
+        text: string;
+    };
+    opShape: {
+        label: string;
+        owner: "schema";
+        invokeOnly: string;
+        evidence: string;
+    };
+    folderMatch: {
+        label: string;
+        owner: "onboard";
+        invokeOnly: string;
+        evidence: string;
+        render: (matches: FolderMatch[]) => string;
+    };
+    harnessPermissions: {
+        label: string;
+        owner: "onboard";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderHarnessPermissions;
+    };
+    teachingLines: {
+        label: string;
+        owner: "onboard";
+        invokeOnly: string;
+        evidence: string;
+        render: typeof renderTeachingLines;
+    };
+};
+export type ItemId = keyof typeof ITEMS;
+export {};