@losthex/scribe 0.1.0

package/README.md

@@ -0,0 +1,33 @@
+# Scribe CLI
+
+Lost Hex's command-line client for Scribe.
+
+## Install
+
+```bash
+npm install --global @losthex/scribe
+```
+
+## Setup
+
+Use the onboarding command provided for your engagement, then sign in:
+
+```bash
+scribe install --project <project> --match <repo> \
+  --issuer <issuer-url> --amend-url <amend-url>
+scribe login
+scribe status
+```
+
+## Commands
+
+```text
+scribe login
+scribe install
+scribe capture
+scribe flush
+scribe amend "<note>"
+scribe status
+scribe log
+scribe uninstall
+```

package/dist/config.js

@@ -0,0 +1,102 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EMPTY_CONFIG = void 0;
+exports.loadConfig = loadConfig;
+exports.saveConfig = saveConfig;
+exports.upsertEngagement = upsertEngagement;
+exports.globMatch = globMatch;
+exports.matchEngagement = matchEngagement;
+exports.resolveSetting = resolveSetting;
+exports.requireSetting = requireSetting;
+/**
+ * `~/.config/scribe/config.json` — what `scribe install` wrote down, and
+ * the one place that decides which repos the collector may look at.
+ *
+ * Engagement matching is a deliberate allowlist (DATA-ITD-005): a commit
+ * is captured only when its repo matches an engagement the engineer
+ * installed, so nothing leaves the machine for personal projects, other
+ * clients, or the many repos that happen to sit on the same laptop. There
+ * is no server-side list to fetch — the amend endpoint is write-only by
+ * design — so the patterns are local config, set once at onboarding.
+ */
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const paths_1 = require("./paths");
+exports.EMPTY_CONFIG = { engagements: [] };
+function loadConfig(paths = (0, paths_1.resolvePaths)()) {
+    let raw;
+    try {
+        raw = (0, node_fs_1.readFileSync)(paths.config, 'utf8');
+    }
+    catch {
+        return { ...exports.EMPTY_CONFIG };
+    }
+    const parsed = JSON.parse(raw);
+    return {
+        ...parsed,
+        engagements: (parsed.engagements ?? []).map((e) => ({
+            project: e.project,
+            match: [...(e.match ?? [])],
+        })),
+    };
+}
+function saveConfig(config, paths = (0, paths_1.resolvePaths)()) {
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(paths.config), { recursive: true });
+    (0, node_fs_1.writeFileSync)(paths.config, `${JSON.stringify(config, null, 2)}\n`, { mode: 0o600 });
+}
+/**
+ * Adds or extends an engagement, keeping `match` de-duplicated so
+ * re-running `scribe install` is idempotent.
+ */
+function upsertEngagement(config, project, match) {
+    const engagements = [...config.engagements];
+    const existing = engagements.findIndex((e) => e.project === project);
+    const patterns = existing >= 0 ? engagements[existing].match : [];
+    const merged = [...new Set([...patterns, ...match])];
+    const entry = { project, match: merged };
+    if (existing >= 0)
+        engagements[existing] = entry;
+    else
+        engagements.push(entry);
+    return { ...config, engagements };
+}
+/**
+ * Case-insensitive match with `*` as the only metacharacter, unanchored —
+ * `bonterratech` and `git@*:bonterratech/*` both match the same remote,
+ * because an engineer writing a pattern is describing a repo, not authoring
+ * a regex.
+ */
+function globMatch(pattern, value) {
+    const needle = pattern.trim().toLowerCase();
+    const haystack = value.toLowerCase();
+    if (needle.length === 0)
+        return false;
+    if (!needle.includes('*'))
+        return haystack.includes(needle);
+    const escaped = needle.replace(/[.+^${}()|[\]\\?]/g, '\\$&').replace(/\*/g, '.*');
+    return new RegExp(escaped).test(haystack);
+}
+/**
+ * The first engagement any of `identifiers` matches, or null — null means
+ * "not a mandated engagement", which means nothing is captured.
+ */
+function matchEngagement(engagements, identifiers) {
+    const candidates = identifiers.filter((value) => Boolean(value));
+    for (const engagement of engagements) {
+        for (const pattern of engagement.match) {
+            if (candidates.some((candidate) => globMatch(pattern, candidate)))
+                return engagement;
+        }
+    }
+    return null;
+}
+/** Flag beats environment beats config, so a one-off override is easy. */
+function resolveSetting(flag, envValue, configured) {
+    return flag ?? envValue ?? configured;
+}
+function requireSetting(value, name, hint) {
+    if (!value)
+        throw new Error(`${name} is not configured — ${hint}`);
+    return value.replace(/\/+$/, '');
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/git.js

@@ -0,0 +1,110 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.scrubRemote = scrubRemote;
+exports.repoIdentity = repoIdentity;
+exports.commitFacts = commitFacts;
+exports.gitConfig = gitConfig;
+exports.setGitConfig = setGitConfig;
+exports.unsetGitConfig = unsetGitConfig;
+/**
+ * The only git the collector runs, and the only data it reads.
+ *
+ * Every command here answers one of two questions: which repo is this, and
+ * what did the commit that just landed look like from the outside. That is
+ * the same shape the server-side collector pulls from the GitHub/GitLab
+ * APIs for engagements Lost Hex can read (DATA-ITD-005) — repo, branch,
+ * sha, subject, timestamp, and a *count* of files. No file names, no
+ * diffs, no message bodies: `git show --stat` and friends are deliberately
+ * absent from this file.
+ */
+const node_child_process_1 = require("node:child_process");
+function runGit(args, cwd) {
+    return (0, node_child_process_1.execFileSync)('git', args, {
+        cwd,
+        encoding: 'utf8',
+        stdio: ['ignore', 'pipe', 'ignore'],
+    }).trim();
+}
+/**
+ * Strips any credentials a remote URL might carry — an installed hook
+ * should never queue `https://user:token@host/...` for transmission.
+ */
+function scrubRemote(remote) {
+    return remote.replace(/^([a-z+]+:\/\/)[^@/]*@/i, '$1');
+}
+function repoIdentity({ cwd = process.cwd(), run = runGit, } = {}) {
+    let root;
+    try {
+        root = run(['rev-parse', '--show-toplevel'], cwd);
+    }
+    catch {
+        return null;
+    }
+    if (!root)
+        return null;
+    const quiet = (args) => {
+        try {
+            const value = run(args, cwd);
+            return value.length > 0 ? value : null;
+        }
+        catch {
+            return null;
+        }
+    };
+    const remote = quiet(['config', '--get', 'remote.origin.url']);
+    return {
+        root,
+        name: root.split('/').filter(Boolean).pop() ?? root,
+        remote: remote ? scrubRemote(remote) : null,
+        branch: quiet(['rev-parse', '--abbrev-ref', 'HEAD']),
+    };
+}
+/**
+ * Facts about `ref` (HEAD by default). The subject is `%s`, which git
+ * already limits to the first line of the message — the body, where people
+ * paste stack traces and snippets, never enters the payload.
+ */
+function commitFacts({ cwd = process.cwd(), run = runGit } = {}, ref = 'HEAD') {
+    let raw;
+    try {
+        raw = run(['log', '-1', '--no-color', '--format=%H%x00%s%x00%aI', ref], cwd);
+    }
+    catch {
+        return null;
+    }
+    const [hash, subject, at] = raw.split('\0');
+    if (!hash || !at)
+        return null;
+    let filesChanged = 0;
+    try {
+        // A count, never the names. `-m --first-parent` gives a merge commit a
+        // sane number instead of nothing.
+        const names = run(['show', '--pretty=format:', '--name-only', '-m', '--first-parent', ref], cwd);
+        filesChanged = new Set(names.split('\n').filter((line) => line.trim().length > 0)).size;
+    }
+    catch {
+        filesChanged = 0;
+    }
+    return { hash, subject: subject || '(no subject)', at, filesChanged };
+}
+/** The value of a git config key, looked up in the given scope. */
+function gitConfig(key, scope = 'global') {
+    try {
+        return runGit(['config', `--${scope}`, '--get', key], process.cwd()) || null;
+    }
+    catch {
+        return null;
+    }
+}
+function setGitConfig(key, value, scope = 'global') {
+    runGit(['config', `--${scope}`, key, value], process.cwd());
+}
+function unsetGitConfig(key, scope = 'global') {
+    try {
+        runGit(['config', `--${scope}`, '--unset', key], process.cwd());
+    }
+    catch {
+        // Already unset.
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/git.js.map

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

package/dist/hook.js

@@ -0,0 +1,115 @@
+"use strict";
+/**
+ * The post-commit shim `scribe install` plants, and the rules for planting
+ * it without breaking anything that was already there.
+ *
+ * Why a hook at all: capture is event-driven because hooks solve repo
+ * discovery for free (SPEC-002) — a post-commit hook fires inside whatever
+ * checkout the commit landed in, so a clone made months after onboarding
+ * self-registers on its first commit, with no path registry to go stale and
+ * no filesystem sweeps across a machine holding client property.
+ *
+ * Why chaining is the hard requirement: `core.hooksPath` is global and it
+ * *overrides* per-repo hooks rather than adding to them, and client repos
+ * routinely carry their own (husky and friends). The shim therefore runs,
+ * in order: the hook that already lived at this path (adopted at install
+ * time), the repo's own `.git/hooks/post-commit` that the global path would
+ * otherwise silence, and only then Scribe's capture — whose failure can
+ * never change the commit's outcome.
+ *
+ * Everything here is a pure string/plan function; install.ts does the IO.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ADOPTED_NAME = exports.HOOK_MARKER = void 0;
+exports.postCommitHook = postCommitHook;
+exports.isScribeHook = isScribeHook;
+exports.planHookInstall = planHookInstall;
+/** Version marker — identifies our own hook on reinstall and uninstall. */
+exports.HOOK_MARKER = '# scribe-local-collector v1';
+/** Where an adopted pre-existing hook is kept, and chained from. */
+exports.ADOPTED_NAME = 'post-commit.pre-scribe';
+/**
+ * The shim itself: POSIX sh, no dependencies, and fail-open by
+ * construction — a broken or missing `scribe` leaves the commit exactly as
+ * it was.
+ *
+ * `scribe capture` is called with the binary's absolute path because GUI
+ * git clients hand hooks a minimal PATH; `command -v scribe` is the
+ * fallback for the day the CLI moves.
+ */
+function postCommitHook({ scribeBin, scribeHome = null }) {
+    const home = scribeHome ? `SCRIBE_HOME="${scribeHome}"\nexport SCRIBE_HOME\n` : '';
+    return `#!/bin/sh
+${exports.HOOK_MARKER} — installed by \`scribe install\` (DATA-ITD-005).
+#
+# Captures commit metadata for configured no-access engagements: repo,
+# branch, sha, subject, timestamp, and a count of files touched. Never
+# diffs, never file names, never code — \`scribe log\` prints everything
+# that was ever sent.
+#
+# Order matters. Anything that was here before scribe runs first, then the
+# repo's own hook (which a global core.hooksPath would otherwise silence),
+# then scribe. The commit's outcome is whatever those hooks decided; scribe
+# never changes it.
+set -u
+
+here=$(CDPATH= cd -- "$(dirname -- "$0")" && pwd -P)
+status=0
+
+if [ -x "$here/${exports.ADOPTED_NAME}" ]; then
+  "$here/${exports.ADOPTED_NAME}" "$@" || status=$?
+fi
+
+# .git/hooks is resolved from the git dir, not via --git-path hooks, which
+# would answer with core.hooksPath — this very directory.
+repo_git_dir=$(git rev-parse --absolute-git-dir 2>/dev/null) || repo_git_dir=""
+if [ -n "$repo_git_dir" ] && [ -x "$repo_git_dir/hooks/post-commit" ]; then
+  repo_hooks=$(CDPATH= cd -- "$repo_git_dir/hooks" && pwd -P)
+  if [ "$repo_hooks" != "$here" ]; then
+    "$repo_git_dir/hooks/post-commit" "$@" || status=$?
+  fi
+fi
+
+${home}SCRIBE_BIN="${scribeBin}"
+if [ ! -x "$SCRIBE_BIN" ]; then
+  SCRIBE_BIN=$(command -v scribe 2>/dev/null) || SCRIBE_BIN=""
+fi
+if [ -n "$SCRIBE_BIN" ]; then
+  "$SCRIBE_BIN" capture --quiet >/dev/null 2>&1 || true
+fi
+
+exit $status
+`;
+}
+/** Whether a hook file on disk is one of ours. */
+function isScribeHook(contents) {
+    return contents.includes(exports.HOOK_MARKER);
+}
+/**
+ * Decides what installing means on this machine, without touching it.
+ *
+ * The rule that matters: an existing global `core.hooksPath` is honoured,
+ * never replaced — the engineer (or their dotfiles, or a company-wide
+ * config) put it there, and Scribe joins that directory instead of taking
+ * the setting over.
+ */
+function planHookInstall(survey) {
+    const hooksPath = survey.globalHooksPath ?? survey.defaultHooksPath;
+    const existing = survey.existingPostCommit;
+    const ours = existing !== null && isScribeHook(existing);
+    let conflict = null;
+    if (existing !== null && !ours && survey.adoptedExists) {
+        conflict =
+            `${hooksPath}/post-commit is not Scribe's and ${hooksPath}/${exports.ADOPTED_NAME} ` +
+                'already exists — move one of them aside, or re-run with --force to replace the shim';
+    }
+    return {
+        hooksPath,
+        setGlobalHooksPath: survey.globalHooksPath === null,
+        adoptExisting: existing !== null && !ours && !survey.adoptedExists,
+        reinstall: ours,
+        conflict,
+        chained: survey.adoptedExists || (existing !== null && !ours) ? exports.ADOPTED_NAME : null,
+    };
+}
+//# sourceMappingURL=hook.js.map

package/dist/hook.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook.js","sourceRoot":"","sources":["../src/hook.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAwBH,wCA2CC;AAGD,oCAEC;AAwCD,0CAoBC;AAlID,2EAA2E;AAC9D,QAAA,WAAW,GAAG,6BAA6B,CAAC;AAEzD,oEAAoE;AACvD,QAAA,YAAY,GAAG,wBAAwB,CAAC;AASrD;;;;;;;;GAQG;AACH,SAAgB,cAAc,CAAC,EAAE,SAAS,EAAE,UAAU,GAAG,IAAI,EAAqB;IAChF,MAAM,IAAI,GAAG,UAAU,CAAC,CAAC,CAAC,gBAAgB,UAAU,yBAAyB,CAAC,CAAC,CAAC,EAAE,CAAC;IACnF,OAAO;EACP,mBAAW;;;;;;;;;;;;;;;;iBAgBI,oBAAY;WAClB,oBAAY;;;;;;;;;;;;;EAarB,IAAI,eAAe,SAAS;;;;;;;;;CAS7B,CAAC;AACF,CAAC;AAED,kDAAkD;AAClD,SAAgB,YAAY,CAAC,QAAgB;IAC3C,OAAO,QAAQ,CAAC,QAAQ,CAAC,mBAAW,CAAC,CAAC;AACxC,CAAC;AAgCD;;;;;;;GAOG;AACH,SAAgB,eAAe,CAAC,MAAkB;IAChD,MAAM,SAAS,GAAG,MAAM,CAAC,eAAe,IAAI,MAAM,CAAC,gBAAgB,CAAC;IACpE,MAAM,QAAQ,GAAG,MAAM,CAAC,kBAAkB,CAAC;IAC3C,MAAM,IAAI,GAAG,QAAQ,KAAK,IAAI,IAAI,YAAY,CAAC,QAAQ,CAAC,CAAC;IAEzD,IAAI,QAAQ,GAAkB,IAAI,CAAC;IACnC,IAAI,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,MAAM,CAAC,aAAa,EAAE,CAAC;QACvD,QAAQ;YACN,GAAG,SAAS,oCAAoC,SAAS,IAAI,oBAAY,GAAG;gBAC5E,qFAAqF,CAAC;IAC1F,CAAC;IAED,OAAO;QACL,SAAS;QACT,kBAAkB,EAAE,MAAM,CAAC,eAAe,KAAK,IAAI;QACnD,aAAa,EAAE,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,aAAa;QAClE,SAAS,EAAE,IAAI;QACf,QAAQ;QACR,OAAO,EAAE,MAAM,CAAC,aAAa,IAAI,CAAC,QAAQ,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,oBAAY,CAAC,CAAC,CAAC,IAAI;KACpF,CAAC;AACJ,CAAC"}