@cluesmith/codev 3.3.4 → 3.3.6

package/dist/lib/skill-refresh.js

@@ -0,0 +1,267 @@
+/**
+ * Refresh shipped provider skills on `codev update` (issue #1811).
+ *
+ * A skill directory is unedited when its content matches a version Codev has shipped
+ * (SHIPPED_SKILL_HASHES, generated from git history). Unedited skills are replaced with
+ * the package's version; an edited one gets a `.codev-new` copy of each differing file
+ * for update's merge session, the same treatment CLAUDE.md and AGENTS.md get.
+ */
+import * as crypto from 'node:crypto';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import { SHIPPED_SKILL_HASHES } from './shipped-skill-hashes.js';
+import { SKILL_PROVIDERS } from './scaffold.js';
+/** Suffix of the new version written beside an edited skill file. */
+export const CODEV_NEW_SUFFIX = '.codev-new';
+/**
+ * Files that never count as skill content: a pending `.codev-new` copy, and Finder's
+ * `.DS_Store`, which would otherwise mark every skill a macOS user opened as edited.
+ */
+function isIgnoredSkillFile(name) {
+    return name.endsWith(CODEV_NEW_SUFFIX) || name === '.DS_Store';
+}
+/**
+ * The content hash of one skill directory: its files in path order, each as path and
+ * content, with line endings normalised so a CRLF checkout of a shipped skill still matches.
+ */
+export function hashSkillFiles(files) {
+    const hash = crypto.createHash('sha256');
+    const sorted = [...files].sort((a, b) => {
+        if (a.path < b.path)
+            return -1;
+        if (a.path > b.path)
+            return 1;
+        return 0;
+    });
+    for (const file of sorted) {
+        hash.update(file.path);
+        hash.update('\0');
+        hash.update(file.content.replace(/\r\n/g, '\n'));
+        hash.update('\0');
+    }
+    return hash.digest('hex');
+}
+/**
+ * The files of a skill directory, or null when the path is not a real directory (missing,
+ * a symlink, or a file). Symlinked entries inside it are read as content, never followed.
+ */
+export function readSkillFiles(dir) {
+    let stat;
+    try {
+        stat = fs.lstatSync(dir);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isDirectory())
+        return null;
+    const files = [];
+    // An unreadable directory or file reads as null, which classifies as not-regular: the
+    // skill is reported and left alone rather than ending the whole update.
+    const walk = (current, prefix) => {
+        for (const entry of fs.readdirSync(current, { withFileTypes: true })) {
+            if (isIgnoredSkillFile(entry.name))
+                continue;
+            const full = path.join(current, entry.name);
+            const rel = prefix + entry.name;
+            if (entry.isDirectory()) {
+                walk(full, `${rel}/`);
+            }
+            else if (entry.isSymbolicLink()) {
+                files.push({ path: rel, content: `<link:${fs.readlinkSync(full)}>`, link: true });
+            }
+            else if (entry.isFile()) {
+                files.push({ path: rel, content: fs.readFileSync(full, 'utf-8') });
+            }
+        }
+    };
+    try {
+        walk(dir, '');
+    }
+    catch {
+        return null;
+    }
+    return files;
+}
+/**
+ * Whether a skill directory holds a pending `.codev-new` that is not a regular file. A
+ * symlinked pending path would carry the next `.codev-new` write outside the project.
+ */
+function hasIrregularPending(dir) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.name.endsWith(CODEV_NEW_SUFFIX) && !entry.isFile())
+            return true;
+        if (entry.isDirectory() && hasIrregularPending(full))
+            return true;
+    }
+    return false;
+}
+/**
+ * Whether `dir` is a real directory holding no skill files: nothing at all, or only
+ * `.DS_Store` / `.codev-new` leftovers. Such a folder is what discarding the untracked files
+ * of an earlier install leaves behind, and it is treated as a missing skill, never a skill.
+ */
+export function isEmptySkillDir(dir) {
+    const files = readSkillFiles(dir);
+    return files !== null && files.length === 0;
+}
+export function hashSkillDir(dir) {
+    const files = readSkillFiles(dir);
+    if (files === null)
+        return null;
+    return hashSkillFiles(files);
+}
+/** Project-relative directory of one provider's copy of a skill, e.g. `.claude/skills/afx`. */
+export function skillRelDir(provider, name) {
+    return `.${provider}/skills/${name}`;
+}
+/**
+ * Where a project's copy of a skill stands against the package's version. `key` is the
+ * skill's project-relative directory (`skillRelDir`), which keys the shipped history.
+ */
+export function classifySkill(projectSkillDir, packageSkillDir, key, history = SHIPPED_SKILL_HASHES) {
+    if (!fs.existsSync(projectSkillDir) && !isSymlink(projectSkillDir))
+        return 'missing';
+    const files = readSkillFiles(projectSkillDir);
+    if (files === null || files.some(file => file.link) || hasIrregularPending(projectSkillDir))
+        return 'not-regular';
+    if (files.length === 0)
+        return 'missing';
+    const projectHash = hashSkillFiles(files);
+    if (projectHash === hashSkillDir(packageSkillDir))
+        return 'current';
+    if ((history[key] ?? []).includes(projectHash))
+        return 'shipped';
+    return 'edited';
+}
+function isSymlink(p) {
+    try {
+        return fs.lstatSync(p).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+function replaceSkillDir(projectSkillDir, packageSkillDir) {
+    // Remove only the files the skill is made of; a .DS_Store is the user's.
+    for (const file of readSkillFiles(projectSkillDir) ?? []) {
+        fs.rmSync(path.join(projectSkillDir, file.path), { force: true });
+    }
+    fs.cpSync(packageSkillDir, projectSkillDir, { recursive: true, force: true });
+}
+/** Write the package's files over the project's copy, leaving any other file in place. */
+function overwritePackagedFiles(projectSkillDir, packageSkillDir) {
+    fs.cpSync(packageSkillDir, projectSkillDir, { recursive: true, force: true });
+}
+/**
+ * Delete a pending `.codev-new` that holds exactly the package's version of its file: the
+ * skill now has that version, so the copy is resolved. A copy with other content is kept.
+ */
+function removeResolvedCodevNew(projectSkillDir, file) {
+    const pending = path.join(projectSkillDir, file.path + CODEV_NEW_SUFFIX);
+    try {
+        if (fs.lstatSync(pending).isFile() && fs.readFileSync(pending, 'utf-8') === file.content)
+            fs.rmSync(pending);
+    }
+    catch {
+        // No pending copy.
+    }
+}
+function removeAllResolvedCodevNew(projectSkillDir, packageSkillDir) {
+    for (const file of readSkillFiles(packageSkillDir) ?? [])
+        removeResolvedCodevNew(projectSkillDir, file);
+}
+/** True when something other than a real directory sits at `p` (a symlink, a file). */
+function existsButNotDirectory(p) {
+    try {
+        const stat = fs.lstatSync(p);
+        return !stat.isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Bring every shipped skill up to date: add missing ones, replace unedited ones, and write
+ * `<file>.codev-new` beside each file of an edited skill that differs from the package. A
+ * file the package adds to an edited skill arrives as `.codev-new` too: whether it belongs
+ * in the user's version of the skill is the merge's call. With `dryRun`, the same result
+ * is reported and nothing is written.
+ */
+export function refreshSkills(targetDir, skeletonDir, options = {}) {
+    const result = { added: [], updated: [], conflicts: [], notRegular: [] };
+    const write = !options.dryRun;
+    for (const provider of SKILL_PROVIDERS) {
+        const relativeSkillsDir = `.${provider}/skills`;
+        const skillsDir = path.join(targetDir, relativeSkillsDir);
+        const srcDir = path.join(skeletonDir, relativeSkillsDir);
+        // A symlinked `.claude` / `.codex` or skills root may be shared beyond this project;
+        // nothing is written through either.
+        const linkedRoot = [`.${provider}`, relativeSkillsDir].find(rel => existsButNotDirectory(path.join(targetDir, rel)));
+        if (linkedRoot) {
+            result.notRegular.push(`${linkedRoot}/`);
+            continue;
+        }
+        if (write && !fs.existsSync(skillsDir))
+            fs.mkdirSync(skillsDir, { recursive: true });
+        // Older/corrupt skeletons may not provide every configured provider.
+        if (!fs.existsSync(srcDir))
+            continue;
+        for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+            if (!entry.isDirectory())
+                continue;
+            const key = skillRelDir(provider, entry.name);
+            const packageSkillDir = path.join(srcDir, entry.name);
+            const projectSkillDir = path.join(skillsDir, entry.name);
+            const state = classifySkill(projectSkillDir, packageSkillDir, key, options.history);
+            if (state === 'missing') {
+                if (write)
+                    fs.cpSync(packageSkillDir, projectSkillDir, { recursive: true });
+                result.added.push(`${key}/`);
+            }
+            else if (state === 'current') {
+                if (write)
+                    removeAllResolvedCodevNew(projectSkillDir, packageSkillDir);
+            }
+            else if (state === 'shipped') {
+                // Every file matched a shipped version, so none of them is the user's to keep.
+                if (write) {
+                    replaceSkillDir(projectSkillDir, packageSkillDir);
+                    removeAllResolvedCodevNew(projectSkillDir, packageSkillDir);
+                }
+                result.updated.push(`${key}/`);
+            }
+            else if (state === 'not-regular') {
+                result.notRegular.push(`${key}/`);
+            }
+            else if (state === 'edited' && options.force) {
+                if (write) {
+                    overwritePackagedFiles(projectSkillDir, packageSkillDir);
+                    removeAllResolvedCodevNew(projectSkillDir, packageSkillDir);
+                }
+                result.updated.push(`${key}/`);
+            }
+            else if (state === 'edited') {
+                const projectFiles = new Map((readSkillFiles(projectSkillDir) ?? []).map(file => [file.path, file.content]));
+                for (const file of readSkillFiles(packageSkillDir) ?? []) {
+                    if (projectFiles.get(file.path) === file.content) {
+                        if (write)
+                            removeResolvedCodevNew(projectSkillDir, file);
+                        continue;
+                    }
+                    if (write) {
+                        const target = path.join(projectSkillDir, file.path);
+                        fs.mkdirSync(path.dirname(target), { recursive: true });
+                        // `wx` after removing a regular pending copy: never follow a path swapped in since.
+                        fs.rmSync(target + CODEV_NEW_SUFFIX, { force: true });
+                        fs.writeFileSync(target + CODEV_NEW_SUFFIX, file.content, { flag: 'wx' });
+                    }
+                    result.conflicts.push(`${key}/${file.path}`);
+                }
+            }
+        }
+    }
+    return result;
+}
+//# sourceMappingURL=skill-refresh.js.map

package/dist/lib/skill-refresh.js.map

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

package/dist/lib/tree-snapshot.d.ts

@@ -0,0 +1,172 @@
+/**
+ * Before/after snapshots of a working tree, for commands that hand the tree to an agent
+ * they cannot sandbox and must report afterwards what moved.
+ *
+ * Two consumers: the consult tripwire (#1649), which watches a review lane that should
+ * write nothing, and `codev bootstrap-docs` (Spec 1797), which watches a drafting agent
+ * that may write only the governance files it was given. Each owns its own exemptions;
+ * this module only takes the snapshots and diffs them through a caller-supplied predicate.
+ *
+ * ## Why not just diff `git status --porcelain` output
+ *
+ * Because the interesting case is a tree that was *already dirty*. A builder mid-phase has
+ * uncommitted work; porcelain reports ` M src/foo.ts` before and after, identical strings,
+ * while the file's contents changed underneath. So the git snapshot pairs each path
+ * porcelain reports with a hash of its contents on disk.
+ *
+ * ## What it cannot see
+ *
+ * In a git work tree: files git ignores, edits inside a submodule (`git status` reports the
+ * submodule as one entry), and an edit restored byte-for-byte before the second snapshot.
+ * Outside git: paths the root `.gitignore` ignores (read with a simplified compiler that can
+ * ignore more than git would), `.git/` and `node_modules/` (so a `git init` and commit made
+ * during the session leave no trace), and anything past the walk's file bound, which the
+ * snapshot reports as `truncated`.
+ */
+/**
+ * Where the repository itself is pointing.
+ *
+ * The working tree is only half the state an agent can move. `git commit` takes a dirty
+ * tree clean, and `git checkout` between two refs with identical content changes nothing a
+ * file comparison can see.
+ *
+ * Either field is `null` when git cannot answer — most usefully in a repository with no
+ * commits yet, where `rev-parse HEAD` fails and the tree is still worth watching.
+ */
+export interface RepositoryIdentity {
+    /** HEAD's object id. */
+    head: string | null;
+    /** Branch name, or `HEAD` when detached. */
+    branch: string | null;
+    /**
+     * True when HEAD names a branch with no commits yet (an unborn branch), so a `null` head
+     * means "no commits" rather than "could not tell" and a first commit is a real move.
+     */
+    unborn?: boolean;
+}
+/**
+ * A point-in-time view of every path that can be compared, plus where the repository was
+ * pointing when it was taken.
+ *
+ * `available: false` means no snapshot could be taken (for `snapshotTree`, most often a
+ * workspace that is not a git repository). Callers say so rather than pretending the tree
+ * was clean.
+ */
+export interface TreeSnapshot {
+    available: boolean;
+    /** Reason the snapshot is unavailable; only set when `available` is false. */
+    reason?: string;
+    /** Repo-relative path → `"<status code>:<content hash>"` (git) or the content hash (walk). */
+    entries: Map<string, string>;
+    /** HEAD and branch at the moment of the snapshot. */
+    identity: RepositoryIdentity;
+    /** Set by the filesystem walk when it stopped at its file bound; entries are then partial. */
+    truncated?: boolean;
+}
+/**
+ * Read HEAD and the branch name in one `git rev-parse`.
+ *
+ * Failure is not fatal to the snapshot. A freshly `git init`ed repository has no HEAD to
+ * resolve, and the file-level half works there perfectly well.
+ */
+export declare function readIdentity(workspaceRoot: string): RepositoryIdentity;
+/**
+ * Paths `consult` writes itself on every run, and which therefore are not
+ * evidence of anything.
+ *
+ * `.consult/history.log` is appended by `logQuery()` after the lane returns, so
+ * it lands inside the window a consult or bootstrap tripwire measures. In this repo `.consult/` is
+ * gitignored and never surfaces — which is exactly why it was not obvious. A
+ * live run against a scratch repo without that entry reported the log file as a
+ * mutation on the very first try. An adopter's `.gitignore` is not something to
+ * depend on for correctness here.
+ */
+export declare const CONSULT_OWNED_PREFIXES: string[];
+/**
+ * Hash a working-tree file, or mark it absent.
+ *
+ * Absent is a real state, not an error: a path can appear in porcelain output as a staged
+ * deletion, and an agent that *deletes* a file is precisely what is being watched for.
+ */
+export declare function hashPath(absolute: string): string;
+/**
+ * Snapshot the git working tree of `workspaceRoot`.
+ *
+ * `-z` (NUL-separated) rather than plain `--porcelain` because git C-quotes paths containing
+ * spaces or non-ASCII in the human-readable form, and a quoted path cannot be handed back to
+ * `fs.readFileSync`. `--untracked-files=all` so a newly created file is listed individually
+ * instead of being collapsed into a single `?? dir/` entry.
+ *
+ * Records HEAD and the branch alongside the paths, so an agent that commits or switches refs
+ * is caught even when no file ends up looking different.
+ */
+export declare function snapshotTree(workspaceRoot: string): TreeSnapshot;
+/** One root `.gitignore` rule, compiled. Negations are not supported (see readRootIgnore). */
+export interface IgnoreRule {
+    regex: RegExp;
+    directoryOnly: boolean;
+}
+/**
+ * Compile the root `.gitignore` for walks outside git (the non-empty-repo rule and the
+ * filesystem snapshot). Only the common subset is honoured (names, `*`/`?`/`**` globs,
+ * anchored and directory-only patterns); `!` negations are skipped, and a `**` between
+ * two path segments can match more than git would, so a walk may ignore more than git,
+ * never less.
+ */
+export declare function readRootIgnore(root: string): IgnoreRule[];
+export declare function isIgnored(rel: string, isDirectory: boolean, rules: IgnoreRule[]): boolean;
+/** Directories the filesystem walk never enters. */
+export declare const FILESYSTEM_WALK_SKIPPED: string[];
+/** How many files the filesystem walk hashes before it gives up and reports `truncated`. */
+export declare const FILESYSTEM_WALK_LIMIT = 50000;
+/**
+ * Snapshot a directory that is not a git work tree: every file's content hash, keyed by its
+ * root-relative path with forward slashes.
+ *
+ * The same scope as the git snapshot: paths the root `.gitignore` ignores are not watched
+ * (they never reach a commit), and `.git/` and `node_modules/` are always skipped. Past
+ * `limit` files the walk stops and marks the snapshot `truncated`, so a caller can say its
+ * detection was partial instead of hashing an unbounded tree.
+ */
+export declare function snapshotFilesystem(root: string, limit?: number): TreeSnapshot;
+/**
+ * A fingerprint of the git index: SHA-256 of `git ls-files --stage -z`, or null when git
+ * cannot answer.
+ *
+ * Porcelain status codes plus working-tree hashes cannot see a re-stage of an already
+ * staged path (`AM` before and after, working file unchanged), so the index needs its own
+ * witness. The staged blob ids are in this listing; their contents are not needed.
+ */
+export declare function readIndexFingerprint(workspaceRoot: string): string | null;
+/**
+ * Paths that differ between two snapshots, sorted, skipping those `isExempt` claims.
+ *
+ * Returns nothing when either snapshot is unavailable: the caller reports that separately,
+ * because "could not look" is not "nothing changed".
+ */
+export declare function diffSnapshotEntries(before: TreeSnapshot, after: TreeSnapshot, isExempt?: (rel: string) => boolean): string[];
+/** One field of the repository's identity that moved between two snapshots. */
+export interface IdentityChange {
+    field: 'HEAD' | 'branch';
+    before: string;
+    after: string;
+}
+/**
+ * Repository identity fields that differ between two snapshots.
+ *
+ * A field that was unreadable at either end is skipped rather than reported as a change:
+ * "we could not tell" and "it moved" are different claims, and only one of them is evidence.
+ * An unborn branch's missing HEAD is not unreadable; it is compared as `(no commits)`.
+ */
+export declare function diffRepositoryIdentity(before: TreeSnapshot, after: TreeSnapshot): IdentityChange[];
+/**
+ * Render a string safe to print to a terminal.
+ *
+ * Path names are bytes, and almost anything that is not `/` or NUL is legal in one —
+ * including newlines and ESC. Printing such a name raw lets it forge the rest of a report:
+ * a file called `\n  - harmless.ts` adds a line to the list, and one containing a CSI
+ * sequence can repaint or erase what is above it. C0, DEL and C1 are escaped; ordinary
+ * Unicode is left alone.
+ */
+export declare function escapeControlChars(value: string): string;
+//# sourceMappingURL=tree-snapshot.d.ts.map

package/dist/lib/tree-snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tree-snapshot.d.ts","sourceRoot":"","sources":["../../src/lib/tree-snapshot.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAOH;;;;;;;;;GASG;AACH,MAAM,WAAW,kBAAkB;IACjC,wBAAwB;IACxB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,4CAA4C;IAC5C,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED;;;;;;;GAOG;AACH,MAAM,WAAW,YAAY;IAC3B,SAAS,EAAE,OAAO,CAAC;IACnB,8EAA8E;IAC9E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,8FAA8F;IAC9F,OAAO,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7B,qDAAqD;IACrD,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,8FAA8F;IAC9F,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAWD;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,kBAAkB,CAatE;AAmCD;;;;;;;;;;GAUG;AACH,eAAO,MAAM,sBAAsB,UAAgB,CAAC;AAEpD;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAUjD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,YAAY,CAAC,aAAa,EAAE,MAAM,GAAG,YAAY,CA8DhE;AAMD,8FAA8F;AAC9F,MAAM,WAAW,UAAU;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,OAAO,CAAC;CACxB;AAqBD;;;;;;GAMG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,EAAE,CAgBzD;AAED,wBAAgB,SAAS,CAAC,GAAG,EAAE,MAAM,EAAE,WAAW,EAAE,OAAO,EAAE,KAAK,EAAE,UAAU,EAAE,GAAG,OAAO,CAEzF;AAED,oDAAoD;AACpD,eAAO,MAAM,uBAAuB,UAA2B,CAAC;AAEhE,4FAA4F;AAC5F,eAAO,MAAM,qBAAqB,QAAS,CAAC;AAE5C;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,GAAE,MAA8B,GAAG,YAAY,CA+BpG;AAED;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAazE;AAED;;;;;GAKG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,YAAY,EACpB,KAAK,EAAE,YAAY,EACnB,QAAQ,GAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAqB,GAC/C,MAAM,EAAE,CAaV;AAKD,+EAA+E;AAC/E,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,GAAG,QAAQ,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,MAAM,CAAC;CACf;AAED;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CAAC,MAAM,EAAE,YAAY,EAAE,KAAK,EAAE,YAAY,GAAG,cAAc,EAAE,CAqBlG;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAUxD"}