@raidiant/notifai 8.0.0 → 9.0.0

package/dist/commands-guidance.js

@@ -2,34 +2,62 @@ import { existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { describeSource } from './config-schema.js';
 import { EXIT } from './commands-core.js';
-import { SHIPPED_GUIDANCE, shippedGuidanceTopic } from './guidance-content.js';
+import { GUIDANCE_TRUST_PREAMBLE, SHIPPED_GUIDANCE, shippedGuidanceTopic, } from './guidance-content.js';
 import { GUIDANCE_TOPIC_MAX_BYTES, GUIDANCE_TOPIC_PATTERN, findProjectGuidanceDir, globalGuidanceDir, personalProjectGuidanceDir, resolveGuidance, } from './guidance.js';
 // ---------------------------------------------------------------------------
 // guidance show / set / unset
 // ---------------------------------------------------------------------------
+/** How each authority is named in the marker above a topic. */
+const AUTHORITY_LABEL = {
+    user: 'you',
+    repository: 'this repository',
+    shipped: 'shipped default',
+};
 /**
- * The whole effective guidance, ready to be followed as read. Each topic is
- * printed under a provenance comment so a reader can tell the user's standing
- * word from the shipped default without the output stopping being Markdown.
+ * The token that makes a marker line ours.
+ *
+ * Without it, a repository topic could open with a handwritten
+ * `<!-- when-to-notify · this machine · /Users/... -->` and everything after
+ * it would read as the User's own standing word. The marker therefore carries
+ * a fixed token, and any occurrence of that token inside file content is
+ * defanged below — so the only lines that can claim to be provenance are the
+ * ones this command wrote.
+ */
+const MARKER_TOKEN = 'notifai:guidance';
+function markerSafe(content) {
+    return content.replaceAll(MARKER_TOKEN, `${MARKER_TOKEN.replace(':', '-')} [not a provenance marker]`);
+}
+/**
+ * The whole effective guidance, ready to be followed as read.
+ *
+ * The trust preamble comes first and belongs to the CLI: it says who supplied
+ * each topic and what no topic may ask for. Each topic then follows its own
+ * marker, so a reader can tell the User's standing word from a repository's
+ * house rules from the shipped default without the output stopping being
+ * Markdown.
  */
 export function guidanceShowCommand(deps, flags) {
     const topics = resolveGuidance({ cwd: deps.cwd, env: deps.env });
     if (flags.json) {
-        deps.io.out(JSON.stringify(topics.map((topic) => ({
-            name: topic.name,
-            source: topic.source,
-            summary: topic.summary,
-            content: topic.content,
-        })), null, 2));
+        deps.io.out(JSON.stringify({
+            trust: GUIDANCE_TRUST_PREAMBLE,
+            topics: topics.map((topic) => ({
+                name: topic.name,
+                source: topic.source,
+                authority: topic.authority,
+                summary: topic.summary,
+                content: topic.content,
+            })),
+        }, null, 2));
         return EXIT.ok;
     }
     const blocks = topics.map((topic) => {
-        const { label, path: filePath } = describeSource(topic.source);
-        const origin = topic.source === 'default' ? 'shipped default' : label;
-        const provenance = filePath === null ? origin : `${origin} · ${filePath}`;
-        return `<!-- ${topic.name} · ${provenance} -->\n${topic.content.trimEnd()}`;
+        const { path: filePath } = describeSource(topic.source);
+        const marker = `<!-- ${MARKER_TOKEN} topic=${topic.name} from=${AUTHORITY_LABEL[topic.authority]}` +
+            `${filePath === null ? '' : ` file=${encodeURIComponent(filePath)}`} -->`;
+        return `${marker}\n${markerSafe(topic.content).trimEnd()}`;
     });
-    deps.io.out(blocks.join('\n\n'));
+    deps.io.out([GUIDANCE_TRUST_PREAMBLE, ...blocks].join('\n\n'));
     return EXIT.ok;
 }
 /**
@@ -57,9 +85,9 @@ async function guidanceMutationTarget(deps, topic, flags) {
         deps.io.interactive === true &&
         deps.io.select) {
         const selected = await deps.io.select('Where should this guidance live?', [
-            { value: 'global', label: 'This machine', hint: 'applies across projects' },
-            { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/' },
-            { value: 'local', label: 'This project (personal)', hint: 'stored on this machine, not in the repo' },
+            { value: 'global', label: 'This machine', hint: 'your standing word, applies across projects' },
+            { value: 'project', label: 'This project (shared)', hint: '.notifai/guidance/ — committed, read as project policy' },
+            { value: 'local', label: 'This project (personal)', hint: 'your standing word here, stored outside the repo' },
         ]);
         if (selected === null) {
             deps.io.err('No guidance layer selected.');
@@ -67,7 +95,7 @@ async function guidanceMutationTarget(deps, topic, flags) {
         }
         layer = selected;
     }
-    return path.join(guidanceLayerDir(deps, layer), `${topic}.md`);
+    return { path: path.join(guidanceLayerDir(deps, layer), `${topic}.md`), layer };
 }
 /**
  * Writes one topic at one layer, replacing the shipped topic of that name for
@@ -92,37 +120,44 @@ export async function guidanceSetCommand(deps, topic, text, flags) {
         const replaces = shipped === undefined
             ? `Add guidance topic "${topic}"`
             : `Replace the shipped "${topic}" guidance for this scope`;
-        const confirmed = await deps.io.confirm(`${replaces} at ${target}?`);
+        const confirmed = await deps.io.confirm(`${replaces} at ${target.path}?`);
         if (!confirmed) {
             deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.');
             return EXIT.usage;
         }
     }
-    mkdirSync(path.dirname(target), { recursive: true });
-    writeFileSync(target, text.endsWith('\n') ? text : `${text}\n`);
-    deps.io.out(`Wrote ${topic} to ${target}`);
+    mkdirSync(path.dirname(target.path), { recursive: true });
+    writeFileSync(target.path, text.endsWith('\n') ? text : `${text}\n`);
+    deps.io.out(`Wrote ${topic} to ${target.path}`);
     if (shipped !== undefined) {
         deps.io.out(`This file now replaces the shipped "${topic}" guidance wherever it applies.`);
     }
+    // A shared file is committed and travels to everyone who clones this
+    // repository, where it is read as the project's policy rather than as
+    // anyone's personal standing word. Worth saying at the moment of writing:
+    // the same sentence means something different in the two locations.
+    if (target.layer === 'project') {
+        deps.io.out('This is shared project policy: it is committed, everyone working here reads it, and it is never read as the User\'s own standing word. Use --local for a personal preference.');
+    }
     return EXIT.ok;
 }
 export async function guidanceUnsetCommand(deps, topic, flags) {
     const target = await guidanceMutationTarget(deps, topic, flags);
     if (target === null)
         return EXIT.usage;
-    if (!existsSync(target)) {
-        deps.io.out(`${topic} is not set at ${target}`);
+    if (!existsSync(target.path)) {
+        deps.io.out(`${topic} is not set at ${target.path}`);
         return EXIT.ok;
     }
     if (!flags.yes) {
-        const confirmed = await deps.io.confirm(`Remove ${target}?`);
+        const confirmed = await deps.io.confirm(`Remove ${target.path}?`);
         if (!confirmed) {
             deps.io.err('Not confirmed. Pass --yes to skip the confirmation gate.');
             return EXIT.usage;
         }
     }
-    rmSync(target, { force: true });
-    deps.io.out(`Removed ${target}; the inherited guidance now applies.`);
+    rmSync(target.path, { force: true });
+    deps.io.out(`Removed ${target.path}; the inherited guidance now applies.`);
     return EXIT.ok;
 }
 //# sourceMappingURL=commands-guidance.js.map

package/dist/commands-guidance.js.map

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

package/dist/commands-hooks.d.ts

@@ -3,14 +3,16 @@ import { type HookHarness } from './hooks.js';
 import { type Harness, type Installation } from './install-hooks.js';
 import { type CommandDeps } from './commands-core.js';
 import { type ActiveHarnessSession } from './commands-harness-context.js';
-export declare const HOOK_EVENTS: readonly ["user-prompt-submit", "stop", "session-end"];
+export declare const HOOK_EVENTS: readonly ["session-start", "subagent-start", "activation-stop", "user-prompt-submit", "stop", "session-end"];
 export type HookEvent = (typeof HOOK_EVENTS)[number];
+/** Lifecycle handlers one installed harness must carry in this CLI build. */
+export declare function requiredHookEvents(harness: Harness): readonly HookEvent[];
 /** SessionEnd cleanup must precede every diagnostic that can wait on a file lock. */
 export declare function hookDefersDiagnosticsUntilAfterCleanup(event: unknown): event is 'session-end';
 /**
  * Runs one harness hook. Contract with every harness: hook JSON arrives on
- * stdin, the decision (if any) goes to stdout, diagnostics go to stderr, and
- * exit 0 with no stdout means "no decision — carry on as normal".
+ * stdin, harness output (if any) goes to stdout, diagnostics go to stderr, and
+ * exit 0 with no stdout means "no decision or added context — carry on as normal".
  *
  * Every failure path in here must reach that no-decision state. A hook that
  * throws, or that blocks past the harness's timeout, degrades the agent for a
@@ -40,6 +42,8 @@ export interface AskFlags {
     multi?: boolean;
     /** Optional Markdown context appended after the question block. */
     body?: string;
+    /** Allow visible backslash-n sequences in `--body`. */
+    literalBackslashN?: boolean;
     /** Raw JSON for a multi-question form; replaces the positional question. */
     form?: string;
     image?: string[];
@@ -99,8 +103,9 @@ export declare function acknowledgeCommand(deps: CommandDeps, requestId: string,
     json?: boolean;
 }): Promise<number>;
 /** Retire a question so a late answer is rejected rather than silently lost. */
-export declare function closeCommand(deps: CommandDeps, requestId: string, flags?: {
+export declare function closeCommand(deps: CommandDeps, requestId: string | undefined, flags?: {
     json?: boolean;
+    pending?: boolean;
 }): Promise<number>;
 export interface HooksInstallFlags {
     harness?: string;