cgraphx 1.4.3 → 2.0.0

package/dist/cli/ui/glyphs.js

@@ -0,0 +1,79 @@
+"use strict";
+/**
+ * Glyph selection for CLI output.
+ *
+ * On Windows, console output is interpreted via the active output codepage.
+ * PowerShell 5.1 and cmd.exe default to OEM codepages (CP437, CP936, ...),
+ * so UTF-8 bytes written to the console render as mojibake. To stay readable
+ * everywhere, we fall back to ASCII glyphs whenever the terminal is not
+ * known to handle UTF-8.
+ *
+ * Detection is intentionally simple:
+ *   - `CGRAPHX_ASCII=1`  -> ASCII (escape hatch for any terminal)
+ *   - `CGRAPHX_UNICODE=1` -> Unicode (opt-in on Windows)
+ *   - Windows              -> ASCII by default
+ *   - Linux kernel console (`TERM=linux`) -> ASCII
+ *   - Everything else      -> Unicode
+ *
+ * Migrated verbatim from cgraphx 1.x (src/ui/glyphs.ts) — the glyph set
+ * is generic CLI output infrastructure, independent of the code-graph layer
+ * that 2.0 removes.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ASCII_GLYPHS = exports.UNICODE_GLYPHS = void 0;
+exports.supportsUnicode = supportsUnicode;
+exports.getGlyphs = getGlyphs;
+exports._resetGlyphsCache = _resetGlyphsCache;
+function supportsUnicode() {
+    if (process.env.CGRAPHX_ASCII === '1')
+        return false;
+    if (process.env.CGRAPHX_UNICODE === '1')
+        return true;
+    if (process.platform === 'win32')
+        return false;
+    return process.env.TERM !== 'linux';
+}
+exports.UNICODE_GLYPHS = {
+    ok: '✓',
+    err: '✗',
+    info: 'ℹ',
+    warn: '⚠',
+    spinner: ['·', '✢', '✳', '✶', '✻', '✽'],
+    barFilled: '█',
+    barEmpty: '░',
+    rail: '│',
+    phaseDone: '◆',
+    dash: '—',
+    hLine: '─',
+    treeBranch: '├── ',
+    treeLast: '└── ',
+    treePipe: '│   ',
+};
+exports.ASCII_GLYPHS = {
+    ok: '[OK]',
+    err: '[ERR]',
+    info: '[i]',
+    warn: '[!]',
+    spinner: ['.', '*', '+', 'x', 'o', 'O'],
+    barFilled: '#',
+    barEmpty: '-',
+    rail: '|',
+    phaseDone: '*',
+    dash: '-',
+    hLine: '-',
+    treeBranch: '|-- ',
+    treeLast: '`-- ',
+    treePipe: '|   ',
+};
+let cached = null;
+function getGlyphs() {
+    if (cached === null) {
+        cached = supportsUnicode() ? exports.UNICODE_GLYPHS : exports.ASCII_GLYPHS;
+    }
+    return cached;
+}
+/** Reset the cached glyph set. Test-only; production code should call `getGlyphs()`. */
+function _resetGlyphsCache() {
+    cached = null;
+}
+//# sourceMappingURL=glyphs.js.map

package/dist/cli/ui/glyphs.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"glyphs.js","sourceRoot":"","sources":["../../../src/cli/ui/glyphs.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG;;;AAEH,0CAKC;AAuDD,8BAKC;AAGD,8CAEC;AAtED,SAAgB,eAAe;IAC7B,IAAI,OAAO,CAAC,GAAG,CAAC,aAAa,KAAK,GAAG;QAAE,OAAO,KAAK,CAAC;IACpD,IAAI,OAAO,CAAC,GAAG,CAAC,eAAe,KAAK,GAAG;QAAE,OAAO,IAAI,CAAC;IACrD,IAAI,OAAO,CAAC,QAAQ,KAAK,OAAO;QAAE,OAAO,KAAK,CAAC;IAC/C,OAAO,OAAO,CAAC,GAAG,CAAC,IAAI,KAAK,OAAO,CAAC;AACtC,CAAC;AAmBY,QAAA,cAAc,GAAW;IACpC,EAAE,EAAE,GAAG;IACP,GAAG,EAAE,GAAG;IACR,IAAI,EAAE,GAAG;IACT,IAAI,EAAE,GAAG;IACT,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACvC,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,IAAI,EAAE,GAAG;IACT,SAAS,EAAE,GAAG;IACd,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;CACjB,CAAC;AAEW,QAAA,YAAY,GAAW;IAClC,EAAE,EAAE,MAAM;IACV,GAAG,EAAE,OAAO;IACZ,IAAI,EAAE,KAAK;IACX,IAAI,EAAE,KAAK;IACX,OAAO,EAAE,CAAC,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,EAAE,GAAG,CAAC;IACvC,SAAS,EAAE,GAAG;IACd,QAAQ,EAAE,GAAG;IACb,IAAI,EAAE,GAAG;IACT,SAAS,EAAE,GAAG;IACd,IAAI,EAAE,GAAG;IACT,KAAK,EAAE,GAAG;IACV,UAAU,EAAE,MAAM;IAClB,QAAQ,EAAE,MAAM;IAChB,QAAQ,EAAE,MAAM;CACjB,CAAC;AAEF,IAAI,MAAM,GAAkB,IAAI,CAAC;AAEjC,SAAgB,SAAS;IACvB,IAAI,MAAM,KAAK,IAAI,EAAE,CAAC;QACpB,MAAM,GAAG,eAAe,EAAE,CAAC,CAAC,CAAC,sBAAc,CAAC,CAAC,CAAC,oBAAY,CAAC;IAC7D,CAAC;IACD,OAAO,MAAM,CAAC;AAChB,CAAC;AAED,wFAAwF;AACxF,SAAgB,iBAAiB;IAC/B,MAAM,GAAG,IAAI,CAAC;AAChB,CAAC"}

package/dist/cli/uninstall.d.ts

@@ -0,0 +1,18 @@
+#!/usr/bin/env node
+/**
+ * cgraphx preuninstall cleanup script.
+ *
+ * Runs automatically when `npm uninstall -g cgraphx` is called (wired via the
+ * `preuninstall` script in package.json).
+ *
+ * 2.0 note: this is now a NO-OP. cgraphx 2.0 has no global (~/.claude) config —
+ * everything is project-local, and a project's `.claude/` + `.cgraphx/` are
+ * cleaned by running `cgraphx uninstall` INSIDE that project, not by
+ * uninstalling the global CLI. There is nothing for this hook to sweep at
+ * npm-uninstall time. The file is kept (package.json references it) so
+ * `npm uninstall -g cgraphx` doesn't error on a missing script.
+ *
+ * This script must never throw — a failed cleanup must not block uninstall.
+ */
+export {};
+//# sourceMappingURL=uninstall.d.ts.map

package/dist/cli/uninstall.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.d.ts","sourceRoot":"","sources":["../../src/cli/uninstall.ts"],"names":[],"mappings":";AACA;;;;;;;;;;;;;;GAcG;AAIH,OAAO,EAAE,CAAC"}

package/dist/cli/uninstall.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * cgraphx preuninstall cleanup script.
+ *
+ * Runs automatically when `npm uninstall -g cgraphx` is called (wired via the
+ * `preuninstall` script in package.json).
+ *
+ * 2.0 note: this is now a NO-OP. cgraphx 2.0 has no global (~/.claude) config —
+ * everything is project-local, and a project's `.claude/` + `.cgraphx/` are
+ * cleaned by running `cgraphx uninstall` INSIDE that project, not by
+ * uninstalling the global CLI. There is nothing for this hook to sweep at
+ * npm-uninstall time. The file is kept (package.json references it) so
+ * `npm uninstall -g cgraphx` doesn't error on a missing script.
+ *
+ * This script must never throw — a failed cleanup must not block uninstall.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=uninstall.js.map

package/dist/cli/uninstall.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"uninstall.js","sourceRoot":"","sources":["../../src/cli/uninstall.ts"],"names":[],"mappings":";;AACA;;;;;;;;;;;;;;GAcG"}

package/dist/cli/upgrade/index.d.ts

@@ -0,0 +1,81 @@
+/**
+ * `cgraphx upgrade` — npm-only self-update.
+ *
+ * cgraphx ships as an npm package, so the single supported download channel is
+ * the npm registry: upgrading shells out to `npm install -g cgraphx@<ver>`.
+ * The 1.x-era "bundle" path (download `install.sh` / a release zip from GitHub)
+ * was removed — those artifacts were never built or published, and a CLI
+ * upgrade should not depend on anything but npm.
+ *
+ * Detection (`detectInstallMethod`) only distinguishes what matters here:
+ *   - **npm**   — installed via `npm i -g cgraphx` (or a local `npm i`); the
+ *                 upgrade performs `npm install -g cgraphx@<ver>`.
+ *   - **npx**   — ephemeral; nothing to upgrade (next `npx` fetches latest).
+ *   - **other** — source checkout / anything else; guided back to npm.
+ */
+export declare const NPM_PACKAGE = "cgraphx";
+export type InstallMethod = {
+    kind: 'npm';
+    scope: 'global' | 'local';
+} | {
+    kind: 'npx';
+} | {
+    kind: 'other';
+    reason: string;
+};
+export interface DetectInput {
+    /** `__filename` of the running CLI module — `<…>/dist/cli/index.js`. */
+    filename: string;
+    platform: NodeJS.Platform;
+    cwd: string;
+}
+export declare function detectInstallMethod(input: DetectInput): InstallMethod;
+export interface Semver {
+    major: number;
+    minor: number;
+    patch: number;
+    pre: string | null;
+}
+export declare function parseSemver(version: string): Semver | null;
+/** Returns >0 if a>b, <0 if a<b, 0 if equal. Throws on unparseable input. */
+export declare function compareVersions(a: string, b: string): number;
+export declare function isUpdateAvailable(current: string, latest: string): boolean;
+/** `0.9.9` / `v0.9.9` → `v0.9.9` (release tags are v-prefixed). */
+export declare function normalizeVersion(v: string): string;
+/** Strip a leading `v`: `v0.9.9` → `0.9.9`. */
+export declare function stripV(v: string): string;
+/**
+ * Resolve the latest published version (e.g. `v2.0.0`) from the npm registry
+ * via `npm view cgraphx version`. npm-only by design — no GitHub dependency.
+ * npm is guaranteed present for anyone who installed via npm/npx, and the
+ * registry has none of the GitHub API's rate-limit problems.
+ */
+export declare function resolveLatestVersion(): Promise<string>;
+export interface UpgradeOptions {
+    /** Pin a specific version (positional arg or CGRAPHX_VERSION). */
+    version?: string;
+    /** Report current vs latest, don't change anything. */
+    check?: boolean;
+    /** Reinstall even if already on the resolved version. */
+    force?: boolean;
+}
+/** Injectable side-effects so the orchestrator stays unit-testable. */
+export interface UpgradeDeps {
+    currentVersion: string;
+    method: InstallMethod;
+    resolveLatest: (pin?: string) => Promise<string>;
+    /** Run a command inheriting stdio; returns its exit code (-1 = spawn failed). */
+    run: (cmd: string, args: string[], env?: NodeJS.ProcessEnv) => number;
+    log: (msg: string) => void;
+    warn: (msg: string) => void;
+    error: (msg: string) => void;
+    platform: NodeJS.Platform;
+}
+/** The honest, additive reminder shown after a successful upgrade. */
+export declare function reindexAdvisory(): string;
+/**
+ * Returns the process exit code (0 = success / nothing to do, 1 = failure).
+ */
+export declare function runUpgrade(opts: UpgradeOptions, deps: UpgradeDeps): Promise<number>;
+export declare function defaultRun(cmd: string, args: string[], env?: NodeJS.ProcessEnv): number;
+//# sourceMappingURL=index.d.ts.map

package/dist/cli/upgrade/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/cli/upgrade/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAKH,eAAO,MAAM,WAAW,YAAY,CAAC;AAMrC,MAAM,MAAM,aAAa,GACrB;IAAE,IAAI,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,QAAQ,GAAG,OAAO,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,KAAK,CAAA;CAAE,GACf;IAAE,IAAI,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEtC,MAAM,WAAW,WAAW;IAC1B,wEAAwE;IACxE,QAAQ,EAAE,MAAM,CAAC;IACjB,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC;CACb;AAMD,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,WAAW,GAAG,aAAa,CAkBrE;AAMD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,GAAG,IAAI,CAAC;CACpB;AAED,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAS1D;AAED,6EAA6E;AAC7E,wBAAgB,eAAe,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,EAAE,MAAM,GAAG,MAAM,CAY5D;AAED,wBAAgB,iBAAiB,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAQ1E;AAED,mEAAmE;AACnE,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGlD;AAED,+CAA+C;AAC/C,wBAAgB,MAAM,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAGxC;AAMD;;;;;GAKG;AACH,wBAAsB,oBAAoB,IAAI,OAAO,CAAC,MAAM,CAAC,CAU5D;AAMD,MAAM,WAAW,cAAc;IAC7B,kEAAkE;IAClE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,yDAAyD;IACzD,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED,uEAAuE;AACvE,MAAM,WAAW,WAAW;IAC1B,cAAc,EAAE,MAAM,CAAC;IACvB,MAAM,EAAE,aAAa,CAAC;IACtB,aAAa,EAAE,CAAC,GAAG,CAAC,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;IACjD,iFAAiF;IACjF,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,KAAK,MAAM,CAAC;IACtE,GAAG,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3B,IAAI,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B,KAAK,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC7B,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;CAC3B;AAUD,sEAAsE;AACtE,wBAAgB,eAAe,IAAI,MAAM,CASxC;AAED;;GAEG;AACH,wBAAsB,UAAU,CAAC,IAAI,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,MAAM,CAAC,CAsDzF;AA+BD,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,GAAG,CAAC,EAAE,MAAM,CAAC,UAAU,GAAG,MAAM,CAIvF"}

package/dist/cli/upgrade/index.js

@@ -0,0 +1,257 @@
+"use strict";
+/**
+ * `cgraphx upgrade` — npm-only self-update.
+ *
+ * cgraphx ships as an npm package, so the single supported download channel is
+ * the npm registry: upgrading shells out to `npm install -g cgraphx@<ver>`.
+ * The 1.x-era "bundle" path (download `install.sh` / a release zip from GitHub)
+ * was removed — those artifacts were never built or published, and a CLI
+ * upgrade should not depend on anything but npm.
+ *
+ * Detection (`detectInstallMethod`) only distinguishes what matters here:
+ *   - **npm**   — installed via `npm i -g cgraphx` (or a local `npm i`); the
+ *                 upgrade performs `npm install -g cgraphx@<ver>`.
+ *   - **npx**   — ephemeral; nothing to upgrade (next `npx` fetches latest).
+ *   - **other** — source checkout / anything else; guided back to npm.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NPM_PACKAGE = void 0;
+exports.detectInstallMethod = detectInstallMethod;
+exports.parseSemver = parseSemver;
+exports.compareVersions = compareVersions;
+exports.isUpdateAvailable = isUpdateAvailable;
+exports.normalizeVersion = normalizeVersion;
+exports.stripV = stripV;
+exports.resolveLatestVersion = resolveLatestVersion;
+exports.reindexAdvisory = reindexAdvisory;
+exports.runUpgrade = runUpgrade;
+exports.defaultRun = defaultRun;
+const path = __importStar(require("path"));
+const child_process_1 = require("child_process");
+exports.NPM_PACKAGE = 'cgraphx';
+function toPosix(p) {
+    return p.replace(/\\/g, '/');
+}
+function detectInstallMethod(input) {
+    const isWin = input.platform === 'win32';
+    // Path math keyed on the TARGET platform so detection is host-independent
+    // (a Windows path resolves correctly even when unit-tested on macOS/Linux).
+    const P = isWin ? path.win32 : path.posix;
+    const norm = toPosix(input.filename);
+    // npx cache: <…>/_npx/<hash>/node_modules/cgraphx/…
+    if (norm.includes('/_npx/')) {
+        return { kind: 'npx' };
+    }
+    // npm install (global or local): lives under a node_modules tree.
+    if (norm.includes('/node_modules/')) {
+        const underCwd = norm.startsWith(toPosix(P.resolve(input.cwd)) + '/');
+        return { kind: 'npm', scope: underCwd ? 'local' : 'global' };
+    }
+    // Anything else (source checkout, legacy layout, unknown) — npm-only now.
+    return { kind: 'other', reason: `not an npm install (running from ${input.filename})` };
+}
+function parseSemver(version) {
+    const m = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?/.exec(version.trim());
+    if (!m)
+        return null;
+    return {
+        major: parseInt(m[1], 10),
+        minor: parseInt(m[2], 10),
+        patch: parseInt(m[3], 10),
+        pre: m[4] ?? null,
+    };
+}
+/** Returns >0 if a>b, <0 if a<b, 0 if equal. Throws on unparseable input. */
+function compareVersions(a, b) {
+    const sa = parseSemver(a);
+    const sb = parseSemver(b);
+    if (!sa || !sb)
+        throw new Error(`cannot compare versions: "${a}" vs "${b}"`);
+    if (sa.major !== sb.major)
+        return sa.major - sb.major;
+    if (sa.minor !== sb.minor)
+        return sa.minor - sb.minor;
+    if (sa.patch !== sb.patch)
+        return sa.patch - sb.patch;
+    // A prerelease is "less than" its release (1.0.0-rc < 1.0.0).
+    if (sa.pre && !sb.pre)
+        return -1;
+    if (!sa.pre && sb.pre)
+        return 1;
+    if (sa.pre && sb.pre)
+        return sa.pre < sb.pre ? -1 : sa.pre > sb.pre ? 1 : 0;
+    return 0;
+}
+function isUpdateAvailable(current, latest) {
+    try {
+        return compareVersions(latest, current) > 0;
+    }
+    catch {
+        // If either is unparseable (e.g. a dev "0.0.0-unknown"), treat differing
+        // strings as "update available" so the user isn't stuck.
+        return normalizeVersion(current) !== normalizeVersion(latest);
+    }
+}
+/** `0.9.9` / `v0.9.9` → `v0.9.9` (release tags are v-prefixed). */
+function normalizeVersion(v) {
+    const t = v.trim();
+    return t.startsWith('v') ? t : `v${t}`;
+}
+/** Strip a leading `v`: `v0.9.9` → `0.9.9`. */
+function stripV(v) {
+    const t = v.trim();
+    return t.startsWith('v') ? t.slice(1) : t;
+}
+// ---------------------------------------------------------------------------
+// Latest-version resolution (npm registry)
+// ---------------------------------------------------------------------------
+/**
+ * Resolve the latest published version (e.g. `v2.0.0`) from the npm registry
+ * via `npm view cgraphx version`. npm-only by design — no GitHub dependency.
+ * npm is guaranteed present for anyone who installed via npm/npx, and the
+ * registry has none of the GitHub API's rate-limit problems.
+ */
+async function resolveLatestVersion() {
+    const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const r = (0, child_process_1.spawnSync)(npm, ['view', exports.NPM_PACKAGE, 'version'], { encoding: 'utf-8' });
+    const version = (r.stdout ?? '').trim();
+    if (r.status !== 0 || !/^\d+\.\d+\.\d+/.test(version)) {
+        throw new Error('could not resolve the latest version from npm. Check your network / registry, or pin a version: `cgraphx upgrade <version>`.');
+    }
+    return normalizeVersion(version);
+}
+const c = {
+    bold: (s) => `\x1b[1m${s}\x1b[0m`,
+    dim: (s) => `\x1b[2m${s}\x1b[0m`,
+    green: (s) => `\x1b[32m${s}\x1b[0m`,
+    yellow: (s) => `\x1b[33m${s}\x1b[0m`,
+    cyan: (s) => `\x1b[36m${s}\x1b[0m`,
+};
+/** The honest, additive reminder shown after a successful upgrade. */
+function reindexAdvisory() {
+    // upgrade is a pure binary swap — it touches no project's `.claude/` config
+    // or `.cgraphx/` data. To pick up this version's skills / hooks / workflow
+    // guidance (and any markdown-parser improvements), re-run install per project.
+    return [
+        c.dim('upgrade 只更新了 CLI 本体,没有改动任何项目的配置。'),
+        c.dim('要让各项目用上这一版的 skills / hooks / 工作方式与解析改进,请到项目内重跑:'),
+        `  ${c.cyan('cgraphx install')}    ${c.dim('# 刷新 .claude/ skills、配置与 .claude/CLAUDE.md')}`,
+    ].join('\n');
+}
+/**
+ * Returns the process exit code (0 = success / nothing to do, 1 = failure).
+ */
+async function runUpgrade(opts, deps) {
+    const { currentVersion, method } = deps;
+    // Resolve the target version (pinned or latest).
+    let latest;
+    try {
+        latest = normalizeVersion(opts.version || (await deps.resolveLatest()));
+    }
+    catch (err) {
+        deps.error(err instanceof Error ? err.message : String(err));
+        return 1;
+    }
+    const currentDisplay = normalizeVersion(currentVersion);
+    deps.log(`${c.bold('cgraphx')}  current ${c.cyan(currentDisplay)}  ${opts.version ? 'target' : 'latest'} ${c.cyan(latest)}`);
+    const updateAvailable = isUpdateAvailable(currentVersion, latest);
+    if (opts.check) {
+        if (updateAvailable) {
+            deps.log(c.yellow(`An update is available: ${currentDisplay} → ${latest}`));
+            deps.log(c.dim('Run `cgraphx upgrade` to install it.'));
+        }
+        else {
+            deps.log(c.green(`You’re on the latest version (${currentDisplay}).`));
+        }
+        return 0;
+    }
+    if (!updateAvailable && !opts.force && !opts.version) {
+        deps.log(c.green(`Already up to date (${currentDisplay}).`));
+        deps.log(c.dim('Use `--force` to reinstall, or `cgraphx upgrade <version>` to change versions.'));
+        return 0;
+    }
+    // npm-only dispatch: npm performs the real update; npx fetches on demand
+    // (nothing to do); anything else is guided back to npm.
+    switch (method.kind) {
+        case 'npm': {
+            // npm version specs have no leading "v" (`@0.9.8`, not `@v0.9.8` — the
+            // latter resolves as a nonexistent dist-tag).
+            const code = upgradeNpm(method, opts.version ? stripV(latest) : 'latest', deps);
+            // Future: when a release changes the `.cgraphx/cgraphx.db` data model, a
+            // schema-migration step would hook in here (after `code === 0`). None yet.
+            return code;
+        }
+        case 'npx':
+            deps.log(c.green('npx always runs the latest version on demand — nothing to upgrade.'));
+            deps.log(c.dim(`Force a fresh fetch with: npx ${exports.NPM_PACKAGE}@latest`));
+            return 0;
+        default:
+            deps.warn(`This cgraphx isn't an npm install (${method.reason}).`);
+            deps.log(c.dim(`Install / upgrade via npm:  npm install -g ${exports.NPM_PACKAGE}@latest`));
+            deps.log(c.dim('(Running from a source checkout? `git pull && npm run build`.)'));
+            return 0;
+    }
+}
+function upgradeNpm(method, versionSpec, deps) {
+    const npm = deps.platform === 'win32' ? 'npm.cmd' : 'npm';
+    const args = method.scope === 'global'
+        ? ['install', '-g', `${exports.NPM_PACKAGE}@${versionSpec}`]
+        : ['install', `${exports.NPM_PACKAGE}@${versionSpec}`];
+    deps.log(c.dim(`Running: ${npm} ${args.join(' ')}`));
+    const code = deps.run(npm, args, process.env);
+    if (code !== 0) {
+        deps.error(`npm exited with code ${code}.`);
+        if (method.scope === 'global') {
+            deps.log(c.dim('If this is a permissions error (EACCES), your global prefix needs sudo, or use a'));
+            deps.log(c.dim('Node version manager (nvm/fnm) so global installs don’t require root.'));
+        }
+        return 1;
+    }
+    deps.log('');
+    deps.log(c.green('✓ Upgrade complete.'));
+    deps.log(reindexAdvisory());
+    return 0;
+}
+// ---------------------------------------------------------------------------
+// Production deps wiring (used by the CLI)
+// ---------------------------------------------------------------------------
+function defaultRun(cmd, args, env) {
+    const r = (0, child_process_1.spawnSync)(cmd, args, { stdio: 'inherit', env: env ?? process.env });
+    if (r.error)
+        return -1;
+    return r.status ?? -1;
+}
+//# sourceMappingURL=index.js.map

package/dist/cli/upgrade/index.js.map

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

package/dist/core/db/index.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Database Base Layer
+ *
+ * SQLite connection management over the built-in `node:sqlite`. This is the
+ * shared, SCHEMA-AGNOSTIC base layer: `open()` creates (or opens) `cgraphx.db`
+ * and applies connection-level PRAGMAs, but applies NO schema and runs NO
+ * migrations. Subsystems that need tables (markdown, timeline) own their own
+ * `ensureSchema` and apply it on top of a connection from `open()`.
+ *
+ * What was removed vs. the cgraphx 1.x lineage:
+ *   - the graph `schema.sql` application (this layer serves non-graph subsystems)
+ *   - `runMigrations` / `getCurrentVersion` / `CURRENT_SCHEMA_VERSION`
+ *   - the `initialize()` factory (open() now creates-or-opens) and
+ *     `getSchemaVersion()` (no shared `schema_versions` table at this layer)
+ */
+import { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
+export { SqliteDatabase, SqliteBackend } from './sqlite-adapter';
+/**
+ * Database connection wrapper with lifecycle management. Schema-agnostic — no
+ * table is assumed to exist. Use `open()` to get a connection, then have the
+ * caller apply its own schema if it needs tables.
+ */
+export declare class DatabaseConnection {
+    private db;
+    private dbPath;
+    private backend;
+    /**
+     * `dev:ino` of the DB file at the moment we opened it (or null when the
+     * platform/filesystem reports no usable inode). Lets us notice when the file
+     * we hold open has been unlinked and REPLACED by a new file at the same path
+     * — `.cgraphx/` deleted and re-`init`ed under a long-lived process — at which
+     * point our fd reads a now-dead inode forever. See `isReplacedOnDisk`.
+     */
+    private openedInode;
+    private constructor();
+    /**
+     * Open a database at `dbPath`, creating it (and its parent directory) if
+     * missing. Applies connection PRAGMAs. Applies NO schema and runs NO
+     * migrations — callers that need tables apply their own `ensureSchema`.
+     */
+    static open(dbPath: string): DatabaseConnection;
+    /**
+     * Get the underlying database instance
+     */
+    getDb(): SqliteDatabase;
+    /**
+     * Get the SQLite backend serving this connection. Per-instance so
+     * cross-project queries report the right backend even when multiple project
+     * DBs are open in the same process.
+     */
+    getBackend(): SqliteBackend;
+    /**
+     * Get database file path
+     */
+    getPath(): string;
+    /**
+     * The journal mode actually in effect (e.g. 'wal', 'delete').
+     *
+     * SQLite silently keeps the prior mode if WAL can't be enabled — e.g. on
+     * filesystems without shared-memory support (some network/virtualized mounts,
+     * WSL2 /mnt). So the effective mode can differ from what
+     * `configureConnection` requested. Surfaced in `cgraphx status` so a
+     * "database is locked" report is triageable: 'wal' ⇒ readers never block on
+     * a writer; anything else ⇒ they can.
+     */
+    getJournalMode(): string;
+    /**
+     * Execute a function within a transaction
+     */
+    transaction<T>(fn: () => T): T;
+    /**
+     * Get database file size in bytes
+     */
+    getSize(): number;
+    /**
+     * Optimize database (vacuum and analyze)
+     */
+    optimize(): void;
+    /**
+     * Lightweight, non-blocking maintenance to run after bulk writes. Two
+     * operations:
+     *
+     *   - `PRAGMA optimize` — incremental ANALYZE; SQLite only re-analyzes tables
+     *     whose row counts changed materially since the last ANALYZE.
+     *
+     *   - `PRAGMA wal_checkpoint(PASSIVE)` — fold pending WAL pages back into the
+     *     main database file so the WAL file doesn't grow unboundedly between
+     *     automatic checkpoints.
+     *
+     * Both operations are silently swallowed on failure — they're a best-effort
+     * optimization, never load-bearing for correctness.
+     */
+    runMaintenance(): void;
+    /**
+     * Close the database connection
+     */
+    close(): void;
+    /**
+     * Check if the database connection is open
+     */
+    isOpen(): boolean;
+    /**
+     * True when the DB file at our path has been REPLACED on disk since we opened
+     * it — a different inode now lives at the same path, so the fd we still hold
+     * points at a now-unlinked inode that can never receive new writes. The
+     * trigger is removing and recreating `.cgraphx/` at the same path under a
+     * long-lived process (`rm -rf .cgraphx` + `cgraphx init`). Returns false when
+     * the inode is unchanged, when the file is momentarily absent (mid-recreate —
+     * nothing to reopen onto yet), or when the platform doesn't report a usable
+     * inode (Windows can't unlink an open file and its st_ino is unreliable, so
+     * this never fires there).
+     */
+    isReplacedOnDisk(): boolean;
+}
+/**
+ * Default database filename
+ */
+export declare const DATABASE_FILENAME = "cgraphx.db";
+/**
+ * Get the default database path for a project
+ */
+export declare function getDatabasePath(projectRoot: string): string;
+//# sourceMappingURL=index.d.ts.map

package/dist/core/db/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/core/db/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,cAAc,EAAE,aAAa,EAAkB,MAAM,kBAAkB,CAAC;AAKjF,OAAO,EAAE,cAAc,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAuBjE;;;;GAIG;AACH,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,EAAE,CAAiB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,OAAO,CAAgB;IAC/B;;;;;;OAMG;IACH,OAAO,CAAC,WAAW,CAAgB;IAEnC,OAAO;IAOP;;;;OAIG;IACH,MAAM,CAAC,IAAI,CAAC,MAAM,EAAE,MAAM,GAAG,kBAAkB;IAY/C;;OAEG;IACH,KAAK,IAAI,cAAc;IAIvB;;;;OAIG;IACH,UAAU,IAAI,aAAa;IAI3B;;OAEG;IACH,OAAO,IAAI,MAAM;IAIjB;;;;;;;;;OASG;IACH,cAAc,IAAI,MAAM;IASxB;;OAEG;IACH,WAAW,CAAC,CAAC,EAAE,EAAE,EAAE,MAAM,CAAC,GAAG,CAAC;IAI9B;;OAEG;IACH,OAAO,IAAI,MAAM;IAKjB;;OAEG;IACH,QAAQ,IAAI,IAAI;IAKhB;;;;;;;;;;;;;OAaG;IACH,cAAc,IAAI,IAAI;IAatB;;OAEG;IACH,KAAK,IAAI,IAAI;IAIb;;OAEG;IACH,MAAM,IAAI,OAAO;IAIjB;;;;;;;;;;OAUG;IACH,gBAAgB,IAAI,OAAO;CAK5B;AAmBD;;GAEG;AACH,eAAO,MAAM,iBAAiB,eAAe,CAAC;AAE9C;;GAEG;AACH,wBAAgB,eAAe,CAAC,WAAW,EAAE,MAAM,GAAG,MAAM,CAE3D"}