@johnfaleke/fathom 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 John Faleke
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,285 @@
+# Fathom
+
+> AI can generate the work. Fathom helps you understand the work.
+
+Fathom is a local-first CLI for project Work State. It gives developers a deterministic, evidence-backed view of what is happening in a repo: what is in progress, what has been completed, what changed, and what may be silently broken.
+
+## Why Fathom exists
+
+Most project tooling answers either:
+
+- which files changed, or
+- what an AI thinks is happening.
+
+Fathom does neither blindly. It focuses on observable evidence and clearly labelled findings:
+
+- missing environment variables
+- undeclared dependencies
+- stale project state
+- changed files grouped by project area
+- a machine-readable snapshot of project health
+
+## Quick start
+
+Install Fathom globally:
+
+```bash
+npm install --global @johnfaleke/fathom
+```
+
+Then run it from any project workspace:
+
+```bash
+cd /path/to/your-project
+fathom init
+fathom check
+fathom status
+```
+
+The package installs the `fathom` command. You do not need to clone this
+repository into the project being inspected.
+
+For repository development, install dependencies locally instead:
+
+```bash
+npm install
+```
+
+Initialize a project:
+
+```bash
+npm run fathom -- init
+```
+
+Set your current work and task state:
+
+```bash
+npm run fathom -- set --current "Ship OAuth integration" --complete "Login API, API docs" --incomplete "Webhook retry handling, Missing README"
+```
+
+Check the project for inconsistencies:
+
+```bash
+npm run fathom -- check
+npm run fathom -- check --json
+```
+
+Review project state:
+
+```bash
+npm run fathom -- status
+npm run fathom -- status --json
+```
+
+See what meaningfully changed:
+
+```bash
+npm run fathom -- diff
+npm run fathom -- diff --json
+```
+
+After building:
+
+```bash
+npm run build
+node dist/cli.js init
+node dist/cli.js status
+```
+
+## Use Fathom in another project
+
+Fathom operates on the current working directory. Build it once, then run the
+CLI while your other project is the working directory.
+
+From PowerShell on Windows:
+
+```powershell
+Set-Location C:\path\to\Fathom
+npm run build
+Set-Location C:\path\to\your-project
+node C:\path\to\Fathom\dist\cli.js init
+node C:\path\to\Fathom\dist\cli.js check
+node C:\path\to\Fathom\dist\cli.js status
+```
+
+From macOS or Linux:
+
+```bash
+cd /path/to/Fathom
+npm run build
+cd /path/to/your-project
+node /path/to/Fathom/dist/cli.js init
+node /path/to/Fathom/dist/cli.js check
+node /path/to/Fathom/dist/cli.js status
+```
+
+Initialization creates `.fathom/` and `.env.example` in the target project.
+The generated `.fathom/` directory is local project state; commit it only if
+you want to share that state with collaborators. Use `--json` for automation:
+
+```bash
+node /path/to/Fathom/dist/cli.js check --json
+node /path/to/Fathom/dist/cli.js status --json
+node /path/to/Fathom/dist/cli.js diff --json
+```
+
+To use the `fathom` command directly during local development, run `npm link`
+once from the Fathom directory. Then open another project and run:
+
+```bash
+fathom init
+fathom check
+fathom status
+```
+
+The direct command works because Fathom always inspects the directory where
+the command is run, not the directory where Fathom itself is installed.
+
+## Open-source project site
+
+The static project site lives in [`site/`](./site/index.html). Open
+`site/index.html` directly in a browser, or serve the repository with any static
+file server while developing. It includes the product overview, installation
+guide, command reference, check interface, Work State schema, contribution links,
+and support link.
+
+The machine-readable [`llms.txt`](./llms.txt) file is a concise text reference for
+AI tools, search systems, and integrations that need to understand Fathom without
+parsing the full README or landing page.
+
+## Package releases
+
+The published package name is `@johnfaleke/fathom`; the installed command remains
+`fathom`. Releases are published automatically by GitHub Actions when a maintainer
+pushes a semantic version tag:
+
+```bash
+git tag v0.1.0
+git push origin v0.1.0
+```
+
+Before the first release, the npm package owner must configure GitHub Actions as a
+trusted publisher for `@johnfaleke/fathom` on npm. Future v0.2 and later tags will
+then build, test, and publish automatically. A version tag does not happen by
+itself; it is the deliberate release switch.
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `fathom init` | Create `.fathom/` for state, config, and event history |
+| `fathom set --current ...` | Update current work and task lists |
+| `fathom status` | Show the current project state |
+| `fathom diff` | Show semantic file changes and project impact |
+| `fathom check` | Detect inconsistent or forgotten wiring |
+
+Add `--json` to any of the reporting commands for machine-readable output.
+
+## Example status output
+
+```text
+FATHOM STATUS
+
+Current work: Ship OAuth integration
+Progress: 1 complete, 1 remaining
+
+Completed:
+  ✓ Login API
+
+Remaining:
+  • Webhook retry handling
+
+Findings:
+  ⚠ left-pad is imported but not declared in package.json
+
+Changes:
+  1 file(s) changed
+  ~ src/app.ts
+
+Attention:
+  1 thing(s) are worth reviewing.
+```
+
+## Example JSON output
+
+```json
+{
+  "version": 1,
+  "updatedAt": "2026-09-20T00:00:00.000Z",
+  "root": "/path/to/project",
+  "currentWork": "Ship OAuth integration",
+  "completed": [
+    { "id": "completed-login-api", "title": "Login API", "status": "completed" }
+  ],
+  "incomplete": [
+    { "id": "incomplete-webhook-retry-handling", "title": "Webhook retry handling", "status": "incomplete" }
+  ],
+  "findings": [
+    {
+      "id": "deps.undeclared-import",
+      "category": "dependencies",
+      "severity": "warning",
+      "message": "left-pad is imported but not declared in package.json",
+      "evidence": []
+    }
+  ],
+  "changes": {
+    "filesChanged": 1,
+    "summary": ["~ src/app.ts"]
+  },
+  "attention": 1
+}
+```
+
+## Built-in checks
+
+The current v0.1 checks are deterministic and evidence-based:
+
+- **config.env-var-missing** — `process.env.X` used but not present in `.env.example`
+- **deps.undeclared-import** — package imported but not declared in `package.json`
+
+## Project configuration guidance
+
+Fathom uses a local `.fathom/config.json` file and respects ignore rules. A good default config is deliberately conservative:
+
+```json
+{
+  "version": 1,
+  "ignore": [
+    "node_modules",
+    "dist",
+    ".git",
+    ".fathom",
+    "coverage",
+    ".next"
+  ]
+}
+```
+
+For more guidance, see [docs/configuration.md](./docs/configuration.md).
+
+## AI interpretation layer (optional)
+
+Fathom intentionally keeps deterministic checks separate from interpretation. If you want AI assistance later, it should be opt-in and use a clean provider interface instead of hard coding a single model provider.
+
+```ts
+export interface AIProvider {
+  id: string;
+  name: string;
+  interpret(input: AIInterpretationRequest): Promise<AIInterpretationResult>;
+}
+```
+
+This keeps the core product honest: evidence stays evidence, and model output remains clearly labelled as interpretation.
+
+See [docs/ai-provider.md](./docs/ai-provider.md) for the provider surface and integration conventions.
+
+## Docs and roadmap
+
+- [FATHOM.md](./FATHOM.md) — vision, principles, and roadmap
+- [docs/configuration.md](./docs/configuration.md) — config and ignore recommendations
+- [docs/ai-provider.md](./docs/ai-provider.md) — optional provider abstraction for interpretation
+
+## License
+
+MIT

package/dist/ai/provider.d.ts

@@ -0,0 +1,20 @@
+export type ProviderType = "openai" | "anthropic" | "google" | "custom";
+export interface AIInterpretationRequest {
+    projectRoot: string;
+    workState: unknown;
+    prompt: string;
+    context?: Record<string, unknown>;
+}
+export interface AIInterpretationResult {
+    summary: string;
+    confidence: number;
+    notes: string[];
+    provider: ProviderType;
+}
+export interface AIProvider {
+    id: string;
+    name: string;
+    type: ProviderType;
+    interpret(input: AIInterpretationRequest): Promise<AIInterpretationResult>;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/ai/provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.d.ts","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,WAAW,GAAG,QAAQ,GAAG,QAAQ,CAAC;AAExE,MAAM,WAAW,uBAAuB;IACtC,WAAW,EAAE,MAAM,CAAC;IACpB,SAAS,EAAE,OAAO,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED,MAAM,WAAW,sBAAsB;IACrC,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;IACnB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,QAAQ,EAAE,YAAY,CAAC;CACxB;AAED,MAAM,WAAW,UAAU;IACzB,EAAE,EAAE,MAAM,CAAC;IACX,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,YAAY,CAAC;IACnB,SAAS,CAAC,KAAK,EAAE,uBAAuB,GAAG,OAAO,CAAC,sBAAsB,CAAC,CAAC;CAC5E"}

package/dist/ai/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/ai/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/ai/provider.ts"],"names":[],"mappings":""}

package/dist/checks/dependencies.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../types.js";
+export declare const dependencyCheck: Check;
+//# sourceMappingURL=dependencies.d.ts.map

package/dist/checks/dependencies.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dependencies.d.ts","sourceRoot":"","sources":["../../src/checks/dependencies.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,KAAK,EAA2B,MAAM,aAAa,CAAC;AAalE,eAAO,MAAM,eAAe,EAAE,KA+E7B,CAAC"}

package/dist/checks/dependencies.js

@@ -0,0 +1,106 @@
+import { builtinModules } from "node:module";
+const NODE_BUILTINS = new Set(builtinModules.flatMap((m) => (m.startsWith("node:") ? [m.slice(5)] : [m])));
+const IMPORT_FROM = /(?:import|export)\s+(?:[\s\S]*?\s+from\s+)?["']([^"']+)["']/g;
+const REQUIRE_CALL = /require\s*\(\s*["']([^"']+)["']\s*\)/g;
+const DYNAMIC_IMPORT = /import\s*\(\s*["']([^"']+)["']\s*\)/g;
+const CODE_EXT = /\.(?:[cm]?[jt]sx?|mjs|cjs)$/;
+export const dependencyCheck = {
+    id: "deps.undeclared-import",
+    async run(ctx) {
+        const pkgRaw = await ctx.readText("package.json");
+        if (!pkgRaw)
+            return [];
+        let pkg;
+        try {
+            pkg = JSON.parse(pkgRaw);
+        }
+        catch {
+            return [];
+        }
+        const declared = new Set([
+            ...Object.keys(pkg.dependencies ?? {}),
+            ...Object.keys(pkg.devDependencies ?? {}),
+            ...Object.keys(pkg.peerDependencies ?? {}),
+            ...Object.keys(pkg.optionalDependencies ?? {}),
+        ]);
+        const used = new Map();
+        for (const file of ctx.files) {
+            if (!CODE_EXT.test(file))
+                continue;
+            const text = await ctx.readText(file);
+            if (!text)
+                continue;
+            const specs = [
+                ...matchAll(text, IMPORT_FROM),
+                ...matchAll(text, REQUIRE_CALL),
+                ...matchAll(text, DYNAMIC_IMPORT),
+            ];
+            for (const spec of specs) {
+                const name = packageName(spec);
+                if (!name)
+                    continue;
+                if (!used.has(name))
+                    used.set(name, new Set());
+                used.get(name).add(file);
+            }
+        }
+        const findings = [];
+        for (const [name, files] of used) {
+            if (declared.has(name))
+                continue;
+            const fileList = [...files].sort();
+            findings.push({
+                id: "deps.undeclared-import",
+                category: "dependencies",
+                severity: "warning",
+                message: `${name} is imported but not declared in package.json`,
+                evidence: [
+                    {
+                        kind: "import",
+                        detail: `Imported in ${fileList.length} file(s)`,
+                        path: fileList[0],
+                    },
+                    ...fileList.slice(0, 5).map((path) => ({
+                        kind: "source",
+                        path,
+                        detail: `import of "${name}"`,
+                    })),
+                    {
+                        kind: "manifest",
+                        path: "package.json",
+                        detail: `${name} is not in dependencies / devDependencies`,
+                    },
+                ],
+            });
+        }
+        return findings;
+    },
+};
+function matchAll(text, re) {
+    const out = [];
+    const copy = new RegExp(re.source, re.flags.includes("g") ? re.flags : re.flags + "g");
+    for (const m of text.matchAll(copy)) {
+        if (m[1])
+            out.push(m[1]);
+    }
+    return out;
+}
+function packageName(spec) {
+    if (spec.startsWith(".") ||
+        spec.startsWith("/") ||
+        spec.startsWith("node:") ||
+        spec.startsWith("#")) {
+        return null;
+    }
+    if (spec.startsWith("@")) {
+        const parts = spec.split("/");
+        if (parts.length < 2)
+            return null;
+        return `${parts[0]}/${parts[1]}`;
+    }
+    const name = spec.split("/")[0] ?? null;
+    if (!name || NODE_BUILTINS.has(name))
+        return null;
+    return name;
+}
+//# sourceMappingURL=dependencies.js.map

package/dist/checks/dependencies.js.map

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

package/dist/checks/env-vars.d.ts

@@ -0,0 +1,3 @@
+import type { Check } from "../types.js";
+export declare const envVarCheck: Check;
+//# sourceMappingURL=env-vars.d.ts.map

package/dist/checks/env-vars.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"env-vars.d.ts","sourceRoot":"","sources":["../../src/checks/env-vars.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAA2B,MAAM,aAAa,CAAC;AAQlE,eAAO,MAAM,WAAW,EAAE,KA4DzB,CAAC"}

package/dist/checks/env-vars.js

@@ -0,0 +1,76 @@
+/** Detects env reads: dot form and bracket form on process env. */
+const ENV_ACCESS = /process\.env(?:\.([A-Z][A-Z0-9_]*)|\[["']([A-Z][A-Z0-9_]*)["']\])/g;
+const CODE_EXT = /\.(?:[cm]?[jt]sx?|mjs|cjs)$/;
+export const envVarCheck = {
+    id: "config.env-var-missing",
+    async run(ctx) {
+        const used = new Map();
+        for (const file of ctx.files) {
+            if (!CODE_EXT.test(file))
+                continue;
+            if (file.includes(".test.") || file.includes(".spec."))
+                continue;
+            const text = await ctx.readText(file);
+            if (!text)
+                continue;
+            for (const match of text.matchAll(ENV_ACCESS)) {
+                const name = match[1] ?? match[2];
+                if (!name)
+                    continue;
+                if (!used.has(name))
+                    used.set(name, new Set());
+                used.get(name).add(file);
+            }
+        }
+        if (used.size === 0)
+            return [];
+        const example = await ctx.readText(".env.example");
+        const documented = parseEnvKeys(example ?? "");
+        const findings = [];
+        for (const [name, files] of used) {
+            if (documented.has(name))
+                continue;
+            const fileList = [...files].sort();
+            findings.push({
+                id: "config.env-var-missing",
+                category: "configuration",
+                severity: "warning",
+                message: `${name} is used in code but missing from .env.example`,
+                evidence: [
+                    {
+                        kind: "env-usage",
+                        detail: `Referenced in ${fileList.length} file(s)`,
+                        path: fileList[0],
+                    },
+                    ...fileList.slice(0, 5).map((path) => ({
+                        kind: "source",
+                        path,
+                        detail: `process.env.${name}`,
+                    })),
+                    {
+                        kind: "missing-doc",
+                        path: ".env.example",
+                        detail: example === null
+                            ? ".env.example does not exist"
+                            : `${name} is not listed in .env.example`,
+                    },
+                ],
+            });
+        }
+        return findings;
+    },
+};
+function parseEnvKeys(contents) {
+    const keys = new Set();
+    for (const line of contents.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        const key = (eq === -1 ? trimmed : trimmed.slice(0, eq)).trim();
+        if (/^[A-Za-z_][A-Za-z0-9_]*$/.test(key))
+            keys.add(key);
+    }
+    return keys;
+}
+//# sourceMappingURL=env-vars.js.map

package/dist/checks/env-vars.js.map

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

package/dist/checks/index.d.ts

@@ -0,0 +1,4 @@
+import type { Check } from "../types.js";
+/** Built-in deterministic checks for v0.1. */
+export declare const builtinChecks: Check[];
+//# sourceMappingURL=index.d.ts.map

package/dist/checks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAIzC,8CAA8C;AAC9C,eAAO,MAAM,aAAa,EAAE,KAAK,EAAmC,CAAC"}

package/dist/checks/index.js

@@ -0,0 +1,5 @@
+import { envVarCheck } from "./env-vars.js";
+import { dependencyCheck } from "./dependencies.js";
+/** Built-in deterministic checks for v0.1. */
+export const builtinChecks = [envVarCheck, dependencyCheck];
+//# sourceMappingURL=index.js.map

package/dist/checks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/checks/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,eAAe,EAAE,MAAM,mBAAmB,CAAC;AAEpD,8CAA8C;AAC9C,MAAM,CAAC,MAAM,aAAa,GAAY,CAAC,WAAW,EAAE,eAAe,CAAC,CAAC"}

package/dist/cli.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=cli.d.ts.map

package/dist/cli.d.ts.map

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