@contextq/cli 0.0.1 → 0.1.0

package/dist/session-hook.js

@@ -0,0 +1,217 @@
+/**
+ * session-hook.ts — idempotent SessionStart boot-hook merge, for BOTH
+ * Claude Code and Codex CLI (T665).
+ *
+ * Targets <root>/.claude/settings.local.json for Claude Code, NOT
+ * settings.json -- mirroring skills/contextq/scripts/install-hook.sh's own
+ * explicit rule: the baked hook command embeds an absolute $HOME/... path,
+ * which is per-machine and MUST stay in a gitignored file, never a
+ * shared/global settings file (see install-hook.sh header comment).
+ *
+ * Codex's own convention treats project-level `.codex/config.toml` /
+ * `.codex/hooks.json` as "trusted-repo settings" meant to be COMMITTED and
+ * shared across a team (verified against developers.openai.com/codex docs,
+ * 2026-08-20: "Project `.codex/config.toml` -> trusted-repo Codex settings
+ * such as sandbox, MCP, hooks, model, or reasoning defaults") -- there is no
+ * Codex-native equivalent of Claude's settings.json/settings.local.json
+ * split. Since the command we write embeds the SAME per-machine absolute
+ * path either way, wireCodexSessionHook() deliberately breaks from that
+ * convention and gitignores `.codex/hooks.json` itself (see
+ * ensureGitignored below) rather than let a per-machine path get committed
+ * and silently break for every teammate whose contextq skill lives
+ * somewhere else (or isn't installed at all).
+ *
+ * This installer POINTS AT the contextq skill's boot script when it is
+ * already installed globally at ~/.claude/skills/contextq -- it never
+ * copies/vendors the skill tree into the target project (out of this
+ * installer's declared write-scope: .mcp.json, .claude/settings*.json,
+ * .codex/hooks.json, .contextq/, and the credential file only).
+ *
+ * ONE shared code path for both harnesses (T665 requirement), in two
+ * layers:
+ *   - buildBootCommand() is the single command-string builder both writers
+ *     call -- same env vars, same shellQuote()-based escaping, same target
+ *     script.
+ *   - mergeSessionStartHook() is the single read-merge-idempotent-write
+ *     implementation both writers call. Claude's `.claude/settings.local.json`
+ *     and Codex's `.codex/hooks.json` use the IDENTICAL JSON shape for a
+ *     SessionStart entry -- { hooks: { SessionStart: [ { hooks: [ { type:
+ *     'command', command } ] } ] } } (verified against Codex's `hooks.json`
+ *     schema at developers.openai.com/codex/hooks, 2026-08-20) -- so there is
+ *     exactly one implementation of "does this file already have our hook,
+ *     and if not, append it", parameterized by which file path to merge
+ *     into. The two exported writers (wireSessionHook, wireCodexSessionHook)
+ *     are thin wrappers supplying only the path + an optional top-level
+ *     default field Codex's schema additionally supports ("description").
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const MARKER = /contextq-boot\.sh|contextq.*boot/;
+/**
+ * T656: POSIX single-quote wrap, safe for any input including shell
+ * metacharacters, unbalanced quotes, backticks, `$()`, `;`, etc. This is the
+ * defense-in-depth layer: slug.ts's validateSlug()/sanitizeSlugFallback()
+ * already constrain --agent/--workspace to a safe charset before they reach
+ * here, but this function must make the written command safe on its own,
+ * because a future caller of wireSessionHook()/wireCodexSessionHook() might
+ * bypass that validation (it takes plain strings, not a branded/validated
+ * type) -- every value substituted into the command string, including
+ * bootScript itself, goes through this.
+ *
+ * Standard technique: wrap in single quotes (nothing is interpolated inside
+ * single quotes in POSIX sh/bash), and for each embedded single quote,
+ * close the quote, emit an escaped literal quote, then reopen: ' -> '\''.
+ */
+export function shellQuote(value) {
+    return `'${value.split("'").join("'\\''")}'`;
+}
+export function ctqBrainBootScript() {
+    return join(homedir(), '.claude', 'skills', 'contextq', 'scripts', 'contextq-boot.sh');
+}
+/**
+ * buildBootCommand — the ONE harness-agnostic command builder (T665). Both
+ * wireSessionHook (Claude) and wireCodexSessionHook (Codex) call this to
+ * produce the exact same shell command string. Codex's SessionStart stdin
+ * contract and its `hookSpecificOutput.additionalContext` output shape are
+ * verified (2026-08-20, developers.openai.com/codex/hooks) to match Claude's
+ * field-for-field (session_id, transcript_path, cwd, hook_event_name on
+ * stdin; the same hookSpecificOutput.additionalContext JSON, or plain text,
+ * on stdout) -- so contextq-boot.sh's existing --hook output needs no
+ * per-harness branching, and this builder needs none either.
+ */
+export function buildBootCommand(agentSlug, workspace, bootScript) {
+    return (`CONTEXTQ_AGENT_SLUG=${shellQuote(agentSlug)} CONTEXTQ_WORKSPACE=${shellQuote(workspace)} ` +
+        `CONTEXTQ_WRITE_WORKSPACE=${shellQuote(workspace)} CONTEXTQ_READ_SCOPE=own+global ` +
+        `bash ${shellQuote(bootScript)} --hook`);
+}
+/**
+ * mergeSessionStartHook — the ONE shared read-merge-idempotent-write core
+ * (T665). See the file header for why this is safe to share verbatim
+ * between Claude's settings.local.json and Codex's hooks.json.
+ */
+function mergeSessionStartHook(target, command, wiredDetail) {
+    const { path, dir, topLevelDefaults } = target;
+    const existed = existsSync(path);
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    let doc = {};
+    if (existed) {
+        const raw = readFileSync(path, 'utf-8');
+        try {
+            doc = raw.trim() === '' ? {} : JSON.parse(raw);
+        }
+        catch (err) {
+            throw new Error(`${path} exists but is not valid JSON (${err.message}) -- refusing to touch it`);
+        }
+    }
+    if (topLevelDefaults) {
+        for (const [key, value] of Object.entries(topLevelDefaults)) {
+            if (doc[key] === undefined)
+                doc[key] = value;
+        }
+    }
+    doc.hooks ??= {};
+    doc.hooks.SessionStart ??= [];
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    const already = doc.hooks.SessionStart.some((entry) => (entry?.hooks ?? []).some((h) => typeof h.command === 'string' && MARKER.test(h.command)));
+    if (already) {
+        return { path, action: 'skipped', detail: 'SessionStart contextq-boot hook already present' };
+    }
+    doc.hooks.SessionStart.push({ hooks: [{ type: 'command', command }] });
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(path, `${JSON.stringify(doc, null, 2)}\n`);
+    return { path, action: 'wired', detail: wiredDetail };
+}
+/**
+ * `bootScriptOverride` exists purely for tests: production callers (index.ts)
+ * always call this with 3 args and get ctqBrainBootScript(), which points at
+ * a real, per-machine, possibly-absent path under $HOME -- tests need to
+ * exercise the "wired" branch deterministically without depending on the
+ * host actually having contextq installed.
+ */
+export function wireSessionHook(root, agentSlug, workspace, bootScriptOverride) {
+    const path = join(root, '.claude', 'settings.local.json');
+    const bootScript = bootScriptOverride ?? ctqBrainBootScript();
+    if (!existsSync(bootScript)) {
+        return {
+            path,
+            action: 'skipped',
+            detail: 'contextq skill not found at ~/.claude/skills/contextq -- MCP tools and the task ' +
+                'manifest are wired, but the memory boot hook needs the skill installed separately first',
+        };
+    }
+    const command = buildBootCommand(agentSlug, workspace, bootScript);
+    return mergeSessionStartHook({ path, dir: join(root, '.claude') }, command, `SessionStart boot hook wired (agent=${agentSlug}, workspace=${workspace})`);
+}
+/**
+ * T665: whether `<root>/.codex/config.toml` ALSO declares an inline
+ * `[hooks]`/`[[hooks.X]]` table. Codex's own docs (developers.openai.com/
+ * codex/hooks, 2026-08-20) state that when one config layer holds both a
+ * `hooks.json` file and an inline `[hooks]` table, "Codex loads both and
+ * warns. Prefer one representation per layer." -- we always write
+ * `hooks.json`, so this surfaces that collision to the installer's own
+ * output instead of leaving it as a silent Codex-side warning nobody sees.
+ */
+function hasInlineHooksTable(root) {
+    const configPath = join(root, '.codex', 'config.toml');
+    if (!existsSync(configPath))
+        return false;
+    const raw = readFileSync(configPath, 'utf-8');
+    return /^\s*\[{1,2}hooks(\.|\])/m.test(raw);
+}
+/**
+ * T665: `.codex/hooks.json` is gitignored the same way `.claude/settings.local.json`
+ * effectively is (see the file header) -- but Codex has no built-in
+ * settings.json/settings.local.json split, so THIS installer has to be the
+ * one to add the .gitignore line, not Codex itself.
+ */
+function ensureGitignored(root, pattern) {
+    if (!existsSync(join(root, '.git')))
+        return;
+    const gitignorePath = join(root, '.gitignore');
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+    const existingLines = new Set(existing.split('\n').map((line) => line.trim()));
+    if (existingLines.has(pattern))
+        return;
+    const block = '\n# .codex/hooks.json embeds a per-machine absolute path (the contextq boot\n' +
+        '# hook command) -- gitignored the same way .claude/settings.local.json is.\n' +
+        '# Each teammate who wants it needs to run `npx contextq init` themselves.\n' +
+        `${pattern}\n`;
+    appendFileSync(gitignorePath, block);
+}
+/**
+ * wireCodexSessionHook — the Codex writer (T665). Same command, same merge
+ * core as wireSessionHook above; only the target path, the top-level
+ * "description" default, and the gitignore step differ. `bootScriptOverride`
+ * exists for the same test-determinism reason as wireSessionHook's.
+ */
+export function wireCodexSessionHook(root, agentSlug, workspace, bootScriptOverride) {
+    const path = join(root, '.codex', 'hooks.json');
+    const bootScript = bootScriptOverride ?? ctqBrainBootScript();
+    if (!existsSync(bootScript)) {
+        return {
+            path,
+            action: 'skipped',
+            detail: 'contextq skill not found at ~/.claude/skills/contextq -- the memory boot hook needs ' +
+                'the skill installed separately first',
+        };
+    }
+    const command = buildBootCommand(agentSlug, workspace, bootScript);
+    const trustNote = 'Codex requires this hook to be TRUSTED before it runs -- start `codex` in this repo and ' +
+        'approve it at the hook-trust prompt (or review/trust via `/hooks` in a session)';
+    const inlineWarning = hasInlineHooksTable(root)
+        ? ` -- WARNING: .codex/config.toml also declares an inline [hooks] table; Codex loads both hooks.json and the inline table and warns on every run. Prefer one representation per layer.`
+        : '';
+    const result = mergeSessionStartHook({
+        path,
+        dir: join(root, '.codex'),
+        topLevelDefaults: {
+            description: 'ContextQ boot hook (managed by `npx contextq init` -- re-run the installer to update, do not hand-edit)',
+        },
+    }, command, `SessionStart boot hook wired (agent=${agentSlug}, workspace=${workspace}). ${trustNote}.${inlineWarning}`);
+    if (result.action === 'wired') {
+        ensureGitignored(root, '.codex/hooks.json');
+    }
+    return result;
+}
+//# sourceMappingURL=session-hook.js.map

package/dist/session-hook.js.map

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

package/dist/skills-sync.d.ts

@@ -0,0 +1,62 @@
+/**
+ * skills-sync.ts — `contextq skills sync <dir>` core logic.
+ *
+ * T698: pulls the caller's tenant-distilled `type='procedure'` contexts
+ * (T376) from the ContextQ API (`GET /api/agent/skills/export?format=json`,
+ * server-side rendering lives in src/services/skill-export.service.ts) and
+ * writes them onto disk as standard Agent Skills folders: `<dir>/<slug>/SKILL.md`.
+ *
+ * THE IDEMPOTENCY KEY IS `metadata.cluster_key`, NOT the folder name or the
+ * skill's title. `runSkillDistillation()` upserts on cluster_key and
+ * rewrites `content`/`name`/`description` IN PLACE on every scheduler tick
+ * that adds a verified session to an existing cluster -- and because the
+ * server-side slug includes a human-readable title prefix, a title rewrite
+ * can change the freshly-computed slug even though the underlying cluster
+ * (and its intended on-disk folder) is unchanged. A sync that keyed off the
+ * freshly-computed slug/title would silently FORK a second folder on the
+ * next run. This module instead reads each existing local folder's own
+ * `metadata.cluster_key` back out of its `SKILL.md` frontmatter (no
+ * separate sidecar index file to go stale) and, when a remote skill's
+ * cluster_key matches an existing folder, REWRITES THAT FOLDER IN PLACE --
+ * even if the server just handed back a different slug for it.
+ *
+ * Orphans (a local folder whose cluster_key is no longer present in the
+ * remote payload -- the source context was deleted, archived, or its
+ * consent was revoked) are REPORTED, never auto-deleted: the file may carry
+ * user edits.
+ *
+ * Network-free and fully unit-testable: `fetchSkills` is injected rather
+ * than hard-wired to `fetch()`, so tests exercise the on-disk merge logic
+ * against an in-memory payload with no server needed.
+ */
+export interface SkillPayload {
+    contextId: number;
+    /** Freshly computed by the server for THIS render -- may differ from the
+     *  folder a matching cluster_key already lives in; see module doc. */
+    slug: string;
+    clusterKey: string;
+    markdown: string;
+}
+export interface SyncResult {
+    written: string[];
+    updated: string[];
+    unchanged: string[];
+    /** Folder names present on disk before this run whose cluster_key is not
+     *  in the remote payload this run. Left on disk untouched. */
+    orphans: string[];
+}
+/**
+ * Pull a scalar value out of the `metadata:` frontmatter block this project
+ * renders (src/services/skill-export.service.ts / yamlString()). Format is
+ * fixed and self-controlled (both write and read side live in this repo),
+ * so a small anchored regex is enough -- no general YAML parser needed.
+ * `^  <key>: "..."$` in multiline mode only matches an indented entry under
+ * `metadata:`, never the top-level `name:`/`description:` lines.
+ */
+export declare function extractFrontmatterMetadataValue(markdown: string, key: string): string | null;
+export declare function extractClusterKey(markdown: string): string | null;
+export interface SyncOptions {
+    dir: string;
+    fetchSkills: () => Promise<SkillPayload[]>;
+}
+export declare function syncSkills(opts: SyncOptions): Promise<SyncResult>;

package/dist/skills-sync.js

@@ -0,0 +1,129 @@
+/**
+ * skills-sync.ts — `contextq skills sync <dir>` core logic.
+ *
+ * T698: pulls the caller's tenant-distilled `type='procedure'` contexts
+ * (T376) from the ContextQ API (`GET /api/agent/skills/export?format=json`,
+ * server-side rendering lives in src/services/skill-export.service.ts) and
+ * writes them onto disk as standard Agent Skills folders: `<dir>/<slug>/SKILL.md`.
+ *
+ * THE IDEMPOTENCY KEY IS `metadata.cluster_key`, NOT the folder name or the
+ * skill's title. `runSkillDistillation()` upserts on cluster_key and
+ * rewrites `content`/`name`/`description` IN PLACE on every scheduler tick
+ * that adds a verified session to an existing cluster -- and because the
+ * server-side slug includes a human-readable title prefix, a title rewrite
+ * can change the freshly-computed slug even though the underlying cluster
+ * (and its intended on-disk folder) is unchanged. A sync that keyed off the
+ * freshly-computed slug/title would silently FORK a second folder on the
+ * next run. This module instead reads each existing local folder's own
+ * `metadata.cluster_key` back out of its `SKILL.md` frontmatter (no
+ * separate sidecar index file to go stale) and, when a remote skill's
+ * cluster_key matches an existing folder, REWRITES THAT FOLDER IN PLACE --
+ * even if the server just handed back a different slug for it.
+ *
+ * Orphans (a local folder whose cluster_key is no longer present in the
+ * remote payload -- the source context was deleted, archived, or its
+ * consent was revoked) are REPORTED, never auto-deleted: the file may carry
+ * user edits.
+ *
+ * Network-free and fully unit-testable: `fetchSkills` is injected rather
+ * than hard-wired to `fetch()`, so tests exercise the on-disk merge logic
+ * against an in-memory payload with no server needed.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+/**
+ * Pull a scalar value out of the `metadata:` frontmatter block this project
+ * renders (src/services/skill-export.service.ts / yamlString()). Format is
+ * fixed and self-controlled (both write and read side live in this repo),
+ * so a small anchored regex is enough -- no general YAML parser needed.
+ * `^  <key>: "..."$` in multiline mode only matches an indented entry under
+ * `metadata:`, never the top-level `name:`/`description:` lines.
+ */
+export function extractFrontmatterMetadataValue(markdown, key) {
+    const re = new RegExp(`^ {2}${key}: "((?:[^"\\\\]|\\\\.)*)"$`, 'm');
+    const match = markdown.match(re);
+    if (!match)
+        return null;
+    // Reverses yamlString()'s escaping (`\` -> `\\`, `"` -> `\"`): a backslash
+    // followed by any one character collapses to that character.
+    return match[1].replace(/\\(.)/g, '$1');
+}
+export function extractClusterKey(markdown) {
+    return extractFrontmatterMetadataValue(markdown, 'cluster_key');
+}
+/**
+ * Discover existing skill folders directly under `dir` by reading each
+ * `SKILL.md`'s own `cluster_key` back out -- this IS the persisted index;
+ * there is no separate sidecar file to go stale. A subdirectory with no
+ * `SKILL.md`, or a `SKILL.md` with no parseable `cluster_key` (not one this
+ * tool wrote, or hand-edited past recognition), is left alone entirely --
+ * never treated as ours to manage.
+ */
+function scanLocalSkills(dir) {
+    if (!existsSync(dir))
+        return [];
+    const entries = [];
+    for (const name of readdirSync(dir)) {
+        const folderPath = join(dir, name);
+        if (!statSync(folderPath).isDirectory())
+            continue;
+        const skillPath = join(folderPath, 'SKILL.md');
+        if (!existsSync(skillPath))
+            continue;
+        const content = readFileSync(skillPath, 'utf-8');
+        const clusterKey = extractClusterKey(content);
+        if (!clusterKey)
+            continue;
+        entries.push({ folder: name, clusterKey });
+    }
+    return entries;
+}
+/** Rewrite the top-level `name: <slug>` frontmatter line to match `folder`,
+ *  so `frontmatter.name` stays equal to the actual directory name (Agent
+ *  Skills convention) even when an existing folder is being reused under a
+ *  different name than the server's freshly-computed slug. Anchored to
+ *  start-of-line so it can never touch the indented `metadata:` entries. */
+function withFrontmatterName(markdown, folder) {
+    return markdown.replace(/^name: .+$/m, `name: ${folder}`);
+}
+export async function syncSkills(opts) {
+    mkdirSync(opts.dir, { recursive: true });
+    const local = scanLocalSkills(opts.dir);
+    const localByClusterKey = new Map(local.map((e) => [e.clusterKey, e.folder]));
+    const usedFolders = new Set(local.map((e) => e.folder));
+    const remote = await opts.fetchSkills();
+    const result = { written: [], updated: [], unchanged: [], orphans: [] };
+    const seenClusterKeys = new Set();
+    for (const skill of remote) {
+        seenClusterKeys.add(skill.clusterKey);
+        const existingFolder = localByClusterKey.get(skill.clusterKey);
+        let folder = existingFolder;
+        if (!folder) {
+            // Brand-new cluster. Prefer the server-computed slug; only fall back
+            // to a suffixed name if an UNRELATED local folder already occupies
+            // it (astronomically unlikely given the slug's hash suffix, but
+            // deterministic and collision-safe rather than silently colliding).
+            folder = usedFolders.has(skill.slug) ? `${skill.slug}-c${skill.contextId}` : skill.slug;
+            usedFolders.add(folder);
+            localByClusterKey.set(skill.clusterKey, folder);
+        }
+        const markdown = folder === skill.slug ? skill.markdown : withFrontmatterName(skill.markdown, folder);
+        const folderPath = join(opts.dir, folder);
+        const skillPath = join(folderPath, 'SKILL.md');
+        const previous = existsSync(skillPath) ? readFileSync(skillPath, 'utf-8') : null;
+        if (previous === markdown) {
+            result.unchanged.push(folder);
+            continue;
+        }
+        mkdirSync(folderPath, { recursive: true });
+        writeFileSync(skillPath, markdown, 'utf-8');
+        result[previous === null ? 'written' : 'updated'].push(folder);
+    }
+    for (const entry of local) {
+        if (!seenClusterKeys.has(entry.clusterKey)) {
+            result.orphans.push(entry.folder);
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=skills-sync.js.map

package/dist/skills-sync.js.map

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

package/dist/slug.d.ts

@@ -0,0 +1,48 @@
+/**
+ * slug.ts — shared slug validation/sanitization for --agent / --workspace.
+ *
+ * T656: the installer used to accept --agent / --workspace verbatim (or fall
+ * back to basename(root), a directory name that can legally contain shell
+ * metacharacters) and interpolate them, unescaped, into a shell command
+ * string written into .claude/settings.local.json's SessionStart hook. That
+ * command runs through a shell on every future session start in the target
+ * repo, so an unsanitized value there is an auto-executing injection.
+ *
+ * SLUG_PATTERN mirrors the slug shape the server itself converges on: every
+ * `slugify()` in the API (src/services/workspace.service.ts,
+ * context.service.ts, tenant-slug.ts) lowercases, then collapses any run of
+ * non [a-z0-9] chars to a single '-', then trims leading/trailing '-'. That
+ * output is always a subset of [a-z0-9][a-z0-9_-]{0,63} — this pattern adds
+ * '_' too (never produced by slugify(), but a common human-typed separator)
+ * and stays deliberately ASCII-lowercase-only so the exact same pattern can
+ * gate both --agent and --workspace with one rule: CLAUDE.md documents
+ * "Workspace slugs are always lowercase" as a product convention, and this
+ * installer extends that same lowercase-only discipline to --agent too
+ * rather than maintaining two different regexes for two fields that both
+ * end up as shell-interpolated env var values. This is a deliberately
+ * STRICTER-than-the-API client-side gate (the boot API's `agent` field is
+ * just `z.string().min(1).max(64)` with no charset check server-side) — the
+ * goal here is never producing a value the API would reject, not permitting
+ * everything the API happens to tolerate.
+ */
+export declare const SLUG_PATTERN: RegExp;
+export declare const SLUG_PATTERN_DESCRIPTION = "lowercase letters, digits, \"-\", \"_\" (must start with a letter/digit, max 64 chars)";
+/**
+ * Validates an EXPLICIT (user-typed) flag value against SLUG_PATTERN.
+ * Throws a clear, actionable error naming the flag, the offending value, and
+ * the allowed pattern -- never silently truncates or mutates an explicit
+ * value (the caller may choose to lowercase --workspace first, since
+ * workspace slugs are documented as always-lowercase in this product; see
+ * index.ts). No such courtesy applies to --agent, which has no such
+ * documented casing convention.
+ */
+export declare function validateSlug(value: string, flagName: string): string;
+/**
+ * Sanitizes a FALLBACK value (basename(root) -- the user never typed this,
+ * it came from the filesystem) into something that always satisfies
+ * SLUG_PATTERN: lowercase, replace every disallowed run with a single '-',
+ * trim leading/trailing separators, cap at 64 chars. An empty result (e.g.
+ * a directory name made entirely of disallowed characters) falls back to
+ * the fixed default 'default' rather than producing an empty/invalid slug.
+ */
+export declare function sanitizeSlugFallback(raw: string): string;

package/dist/slug.js

@@ -0,0 +1,62 @@
+/**
+ * slug.ts — shared slug validation/sanitization for --agent / --workspace.
+ *
+ * T656: the installer used to accept --agent / --workspace verbatim (or fall
+ * back to basename(root), a directory name that can legally contain shell
+ * metacharacters) and interpolate them, unescaped, into a shell command
+ * string written into .claude/settings.local.json's SessionStart hook. That
+ * command runs through a shell on every future session start in the target
+ * repo, so an unsanitized value there is an auto-executing injection.
+ *
+ * SLUG_PATTERN mirrors the slug shape the server itself converges on: every
+ * `slugify()` in the API (src/services/workspace.service.ts,
+ * context.service.ts, tenant-slug.ts) lowercases, then collapses any run of
+ * non [a-z0-9] chars to a single '-', then trims leading/trailing '-'. That
+ * output is always a subset of [a-z0-9][a-z0-9_-]{0,63} — this pattern adds
+ * '_' too (never produced by slugify(), but a common human-typed separator)
+ * and stays deliberately ASCII-lowercase-only so the exact same pattern can
+ * gate both --agent and --workspace with one rule: CLAUDE.md documents
+ * "Workspace slugs are always lowercase" as a product convention, and this
+ * installer extends that same lowercase-only discipline to --agent too
+ * rather than maintaining two different regexes for two fields that both
+ * end up as shell-interpolated env var values. This is a deliberately
+ * STRICTER-than-the-API client-side gate (the boot API's `agent` field is
+ * just `z.string().min(1).max(64)` with no charset check server-side) — the
+ * goal here is never producing a value the API would reject, not permitting
+ * everything the API happens to tolerate.
+ */
+export const SLUG_PATTERN = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+export const SLUG_PATTERN_DESCRIPTION = 'lowercase letters, digits, "-", "_" (must start with a letter/digit, max 64 chars)';
+/**
+ * Validates an EXPLICIT (user-typed) flag value against SLUG_PATTERN.
+ * Throws a clear, actionable error naming the flag, the offending value, and
+ * the allowed pattern -- never silently truncates or mutates an explicit
+ * value (the caller may choose to lowercase --workspace first, since
+ * workspace slugs are documented as always-lowercase in this product; see
+ * index.ts). No such courtesy applies to --agent, which has no such
+ * documented casing convention.
+ */
+export function validateSlug(value, flagName) {
+    if (!SLUG_PATTERN.test(value)) {
+        throw new Error(`${flagName} value "${value}" is not a valid slug -- allowed: ${SLUG_PATTERN_DESCRIPTION}`);
+    }
+    return value;
+}
+/**
+ * Sanitizes a FALLBACK value (basename(root) -- the user never typed this,
+ * it came from the filesystem) into something that always satisfies
+ * SLUG_PATTERN: lowercase, replace every disallowed run with a single '-',
+ * trim leading/trailing separators, cap at 64 chars. An empty result (e.g.
+ * a directory name made entirely of disallowed characters) falls back to
+ * the fixed default 'default' rather than producing an empty/invalid slug.
+ */
+export function sanitizeSlugFallback(raw) {
+    let out = raw
+        .toLowerCase()
+        .replace(/[^a-z0-9_-]+/g, '-')
+        .replace(/^[-_]+|[-_]+$/g, '');
+    out = out.slice(0, 64);
+    out = out.replace(/[-_]+$/g, '');
+    return out === '' ? 'default' : out;
+}
+//# sourceMappingURL=slug.js.map

package/dist/slug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"slug.js","sourceRoot":"","sources":["../src/slug.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;GA0BG;AAEH,MAAM,CAAC,MAAM,YAAY,GAAG,4BAA4B,CAAC;AAEzD,MAAM,CAAC,MAAM,wBAAwB,GAAG,oFAAoF,CAAC;AAE7H;;;;;;;;GAQG;AACH,MAAM,UAAU,YAAY,CAAC,KAAa,EAAE,QAAgB;IAC1D,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,KAAK,CAAC,EAAE,CAAC;QAC9B,MAAM,IAAI,KAAK,CACb,GAAG,QAAQ,WAAW,KAAK,qCAAqC,wBAAwB,EAAE,CAC3F,CAAC;IACJ,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAAC,GAAW;IAC9C,IAAI,GAAG,GAAG,GAAG;SACV,WAAW,EAAE;SACb,OAAO,CAAC,eAAe,EAAE,GAAG,CAAC;SAC7B,OAAO,CAAC,gBAAgB,EAAE,EAAE,CAAC,CAAC;IAEjC,GAAG,GAAG,GAAG,CAAC,KAAK,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IACvB,GAAG,GAAG,GAAG,CAAC,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC,CAAC;IAEjC,OAAO,GAAG,KAAK,EAAE,CAAC,CAAC,CAAC,SAAS,CAAC,CAAC,CAAC,GAAG,CAAC;AACtC,CAAC"}

package/dist/tasks-init.d.ts

@@ -0,0 +1,14 @@
+/**
+ * tasks-init.ts — scaffold .contextq/tasks/TASKS.md.
+ *
+ * Mirrors skills/contextq/scripts/ctq-tasks-init.sh 1:1 (same manifest
+ * header, same idempotent "leave it alone if it exists" behavior, same
+ * narrow 3-line .gitignore patch for the churny per-machine overlay files).
+ * Does not touch anything else in .gitignore.
+ */
+export interface TasksInitResult {
+    path: string;
+    action: 'created' | 'skipped';
+    detail: string;
+}
+export declare function initTasksDir(root: string): TasksInitResult;

package/dist/tasks-init.js

@@ -0,0 +1,51 @@
+/**
+ * tasks-init.ts — scaffold .contextq/tasks/TASKS.md.
+ *
+ * Mirrors skills/contextq/scripts/ctq-tasks-init.sh 1:1 (same manifest
+ * header, same idempotent "leave it alone if it exists" behavior, same
+ * narrow 3-line .gitignore patch for the churny per-machine overlay files).
+ * Does not touch anything else in .gitignore.
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+function manifestHeader(project) {
+    return `# Tasks: ${project}
+<!-- ctq-tasks manifest v1 (T442, repo-local fork of nf-tasks). Status tokens: [backlog] [todo] [doing] [done] [forbidden]. -->
+<!-- "blocked" is DERIVED — never a manual status. Two kinds: deps not all [done], OR a -->
+<!-- "blocker: <reason>" line on a [todo] (external wait); clear the line to release it. -->
+<!-- [backlog] = not ready yet; excluded from run planning. Promote with: flip todo <id> -->
+<!-- [forbidden] = too dangerous to ever run — permanent tombstone. Add 'reason: <why>'. -->
+<!--   Never archived. Flip back to todo only if mis-classified. -->
+<!--   Set with: flip forbidden <id>  -->
+<!-- Task header format is parsed: "## T<NN> [status] <free-text title>". Keep the id+status shape. -->
+<!-- See docs/tech/ctq-tasks-sync.md for the field mapping this manifest syncs against. -->
+
+`;
+}
+function patchGitignore(root) {
+    if (!existsSync(join(root, '.git')))
+        return;
+    const gitignorePath = join(root, '.gitignore');
+    const patterns = ['.contextq/tasks/status.log', '.contextq/tasks/.reconcile.lock/', '.contextq/tasks/sync-map.json'];
+    const existing = existsSync(gitignorePath) ? readFileSync(gitignorePath, 'utf-8') : '';
+    const existingLines = new Set(existing.split('\n').map((line) => line.trim()));
+    const missing = patterns.filter((p) => !existingLines.has(p));
+    if (missing.length === 0)
+        return;
+    const block = '\n# .contextq/tasks/ — TASKS.md + TASKS_ARCHIVE.md are tracked; the\n' +
+        '# overlay/lock/sync-map below are machine-local and ephemeral\n' +
+        missing.map((p) => `${p}\n`).join('');
+    appendFileSync(gitignorePath, block);
+}
+export function initTasksDir(root) {
+    const tasksDir = join(root, '.contextq', 'tasks');
+    const manifest = join(tasksDir, 'TASKS.md');
+    mkdirSync(tasksDir, { recursive: true });
+    patchGitignore(root);
+    if (existsSync(manifest)) {
+        return { path: manifest, action: 'skipped', detail: 'manifest already exists — left untouched' };
+    }
+    writeFileSync(manifest, manifestHeader(basename(root)));
+    return { path: manifest, action: 'created', detail: 'task manifest scaffolded' };
+}
+//# sourceMappingURL=tasks-init.js.map

package/dist/tasks-init.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tasks-init.js","sourceRoot":"","sources":["../src/tasks-init.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAAE,cAAc,EAAE,UAAU,EAAE,SAAS,EAAE,YAAY,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAC7F,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAQ3C,SAAS,cAAc,CAAC,OAAe;IACrC,OAAO,YAAY,OAAO;;;;;;;;;;;CAW3B,CAAC;AACF,CAAC;AAED,SAAS,cAAc,CAAC,IAAY;IAClC,IAAI,CAAC,UAAU,CAAC,IAAI,CAAC,IAAI,EAAE,MAAM,CAAC,CAAC;QAAE,OAAO;IAE5C,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC,CAAC;IAC/C,MAAM,QAAQ,GAAG,CAAC,4BAA4B,EAAE,kCAAkC,EAAE,+BAA+B,CAAC,CAAC;IAErH,MAAM,QAAQ,GAAG,UAAU,CAAC,aAAa,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,aAAa,EAAE,OAAO,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;IACvF,MAAM,aAAa,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,GAAG,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC;IAC/E,MAAM,OAAO,GAAG,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC;IAC9D,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC;QAAE,OAAO;IAEjC,MAAM,KAAK,GACT,uEAAuE;QACvE,iEAAiE;QACjE,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAExC,cAAc,CAAC,aAAa,EAAE,KAAK,CAAC,CAAC;AACvC,CAAC;AAED,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,MAAM,QAAQ,GAAG,IAAI,CAAC,IAAI,EAAE,WAAW,EAAE,OAAO,CAAC,CAAC;IAClD,MAAM,QAAQ,GAAG,IAAI,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IAE5C,SAAS,CAAC,QAAQ,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,cAAc,CAAC,IAAI,CAAC,CAAC;IAErB,IAAI,UAAU,CAAC,QAAQ,CAAC,EAAE,CAAC;QACzB,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,0CAA0C,EAAE,CAAC;IACnG,CAAC;IAED,aAAa,CAAC,QAAQ,EAAE,cAAc,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IACxD,OAAO,EAAE,IAAI,EAAE,QAAQ,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,0BAA0B,EAAE,CAAC;AACnF,CAAC"}