@lucas-bur/pix 0.3.0 → 0.5.0

package/README.md

@@ -1,18 +1,11 @@
 # @lucas-bur/pix
 
-[![CI](https://github.com/lucas-bur/pix/actions/workflows/ci.yml/badge.svg)](https://github.com/lucas-bur/pix/actions/workflows/ci.yml)
-[![codecov](https://codecov.io/gh/lucas-bur/pix/branch/main/graph/badge.svg)](https://codecov.io/gh/lucas-bur/pix)
+[![CI](https://github.com/Lucas-Bur/pix/actions/workflows/ci.yml/badge.svg)](https://github.com/Lucas-Bur/pix/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/Lucas-Bur/pix/branch/main/graph/badge.svg)](https://codecov.io/gh/Lucas-Bur/pix)
 [![npm version](https://img.shields.io/npm/v/@lucas-bur/pix)](https://www.npmjs.com/package/@lucas-bur/pix)
 [![npm downloads](https://img.shields.io/npm/dm/@lucas-bur/pix)](https://www.npmjs.com/package/@lucas-bur/pix)
-[![Code Quality](https://img.shields.io/badge/code%20quality-fallow-blue)](https://github.com/fallow-rs/fallow)
 
-Lightweight local semantic project indexer (short pix)
-
-Zero external services, 100% local + offline. Installs as a devDependency and provides agent-ready structured JSON output.
-
-## Status
-
-MVP in development. See [CONTEXT.md](./CONTEXT.md) for architecture decisions and [.scratch/pix-mvp/PRD.md](./.scratch/pix-mvp/PRD.md) for the product requirements.
+Lightweight local semantic project indexer. Zero external services, 100% local and offline. Installs as a devDependency and provides agent-ready structured JSON output.
 
 ## Quick Start
 
@@ -23,23 +16,46 @@ pix index
 pix query "authentication middleware"
 ```
 
-## Quality Gates
+## Commands
+
+| Command              | Description                                 | JSON flag |
+| -------------------- | ------------------------------------------- | --------- |
+| `pix init`           | Create `.pix/config.json` with defaults     | `--json`  |
+| `pix index`          | Scan, chunk, embed, and store project files | `--json`  |
+| `pix query "<text>"` | Semantic search via cosine similarity       | `--json`  |
+| `pix status`         | Show index statistics                       | `--json`  |
+| `pix reset`          | Delete index files (chunks + vectors)       | `--json`  |
+
+All commands support `--json` for structured output on stdout — ideal for piping to AI agents.
+
+## Agent-Ready Output
 
-This project uses [fallow](https://github.com/fallow-rs/fallow) for static analysis (dead code, duplication, complexity).
+```bash
+$ pix status --json
+{"chunks":59,"files":37,"model":"Xenova/all-MiniLM-L6-v2","lastIndex":1715030400000,"totalLines":1260,"byteSize":16128}
+```
+
+Errors use the same structured format:
+
+```json
+{ "error": true, "code": "CONFIG_MISSING", "message": "No .pix/config.json found" }
+```
 
-### Commands
+## Architecture
 
-- `vp run lint:fallow` — Run fallow with JSON output (used in CI)
-- `fallow audit --summary` — Check only changed files (used in pre-commit hook)
+pix follows hexagonal architecture (ports and adapters) with three layers:
 
-### Pre-commit Hook
+- **Domain** (`src/domain/`) — Pure types, entities, port declarations
+- **Application** (`src/application/`) — Use cases orchestrating business logic
+- **Infrastructure** (`src/services/`) — Concrete adapters (ONNX, filesystem, ffmpeg scanning)
 
-The pre-commit hook is managed by vite-plus and runs:
+See [CONTEXT.md](./CONTEXT.md) for architecture decisions and [docs/adr/](./docs/adr/) for decision records.
 
-1. `vp staged` — Formats, lints, and type-checks staged files
-2. `fallow audit --summary` — Audits changed files for quality issues
+## Quality
 
-To set up hooks after cloning: `vp config`
+- `vp check` — Format, lint, type-check
+- `vp test` — Unit and integration tests
+- `vp run lint:fallow` — Dead code, duplication, complexity analysis
 
 ## License
 

package/dist/index.mjs

@@ -1,12 +1,11 @@
 #!/usr/bin/env node
 import { createRequire } from "node:module";
 import { NodeContext, NodeRuntime } from "@effect/platform-node";
-import { Clock, Context, Data, Effect, Layer, Option } from "effect";
-import { Args, Command, Options } from "@effect/cli";
+import { Clock, Console, Context, Data, Effect, Layer, Option } from "effect";
+import { Args, CliConfig, Command, Options } from "@effect/cli";
 import crypto from "node:crypto";
 import { FileSystem } from "@effect/platform";
 import { env } from "@huggingface/transformers";
-import fg from "fast-glob";
 import ignore from "ignore";
 //#region src/domain/ports.ts
 var ConfigStore = class extends Context.Tag("ConfigStore")() {};
@@ -68,15 +67,13 @@ var IndexProject = class extends Effect.Service()("IndexProject", {
 			const embeddings = yield* embedder.batch(texts);
 			yield* vectorStore.store(allChunks, embeddings);
 			const dims = embeddings[0]?.dims ?? 384;
-			const byteSize = embeddings.length * dims * 4;
-			yield* Effect.logInfo(`Indexed ${totalChunks} chunks from ${totalFiles} files.`);
 			return {
 				success: true,
 				stats: {
 					chunks: totalChunks,
 					files: totalFiles,
 					totalLines,
-					byteSize
+					byteSize: embeddings.length * dims * 4
 				}
 			};
 		});
@@ -135,6 +132,26 @@ var ResetIndex = class extends Effect.Service()("ResetIndex", {
 	})
 }) {};
 //#endregion
+//#region src/lib/error-format.ts
+const errorCodes = {
+	ConfigError: "CONFIG_MISSING",
+	PlatformError: "PLATFORM_ERROR"
+};
+const messageFromError = (error) => {
+	if (typeof error === "string") return error;
+	if (error && typeof error === "object" && "message" in error) return String(error.message);
+	return "Unknown error";
+};
+const codeFromError = (error) => {
+	if (error && typeof error === "object" && "_tag" in error) return errorCodes[String(error._tag)] ?? "UNKNOWN";
+	return "UNKNOWN";
+};
+const formatError = (error) => JSON.stringify({
+	error: true,
+	code: codeFromError(error),
+	message: messageFromError(error)
+});
+//#endregion
 //#region src/commands/index-cmd.ts
 /** CLI command: pix index [--force] [--verbose] [--json] */
 const indexCommand = Command.make("index", {
@@ -142,39 +159,28 @@ const indexCommand = Command.make("index", {
 	verbose: Options.boolean("verbose").pipe(Options.withDefault(false)),
 	json: Options.boolean("json").pipe(Options.withDefault(false))
 }, ({ force, verbose, json }) => Effect.gen(function* () {
-	if (force) yield* Effect.logInfo(`--force is currently not implemented and only a placeholder.`);
-	if (verbose) yield* Effect.logInfo(`--verbose is currently not implemented and only a placeholder.`);
+	if (force && !json) yield* Effect.logInfo("--force is currently not implemented and only a placeholder.");
+	if (verbose && !json) yield* Effect.logInfo("--verbose is currently not implemented and only a placeholder.");
 	const startTime = Date.now();
 	const result = yield* IndexProject.index().pipe(Effect.either);
-	if (result._tag === "Left") {
-		const error = result.left;
-		const message = error.message ?? String(error);
-		yield* Effect.sync(() => {
-			console.log(JSON.stringify({ error: message }));
-		});
-		return yield* Effect.fail(error);
-	}
+	if (result._tag === "Left") return yield* Effect.fail(result.left);
 	const duration = `${((Date.now() - startTime) / 1e3).toFixed(1)}s`;
-	if (json) return yield* Effect.sync(() => {
-		console.log(JSON.stringify({
-			chunks: result.right.stats.chunks,
-			files: result.right.stats.files,
-			duration
-		}));
-	});
+	if (json) return yield* Console.log(JSON.stringify({
+		chunks: result.right.stats.chunks,
+		files: result.right.stats.files,
+		duration
+	}));
 	yield* Effect.logInfo(`Indexed ${result.right.stats.chunks} chunks from ${result.right.stats.files} files in ${duration}.`);
-}));
+}).pipe(Effect.tapError((error) => Console.log(formatError(error)))));
 //#endregion
 //#region src/commands/init.ts
 /** CLI command: pix init [--json] */
 const initCommand = Command.make("init", { json: Options.boolean("json").pipe(Options.withDefault(false)) }, ({ json }) => Effect.gen(function* () {
 	const result = yield* InitProject.init();
-	if (json) return yield* Effect.sync(() => {
-		console.log(JSON.stringify(result, null, 2));
-	});
+	if (json) return yield* Console.log(JSON.stringify(result, null, 2));
 	yield* Effect.logInfo("Created .pix/config.json with default settings.");
 	yield* Effect.logInfo("Reminder: Add `.pix` to your `.gitignore` file to avoid committing the index.");
-}));
+}).pipe(Effect.tapError((error) => Console.log(formatError(error)))));
 //#endregion
 //#region src/commands/query.ts
 const DEFAULT_TOP_K = 5;
@@ -214,7 +220,7 @@ const queryCommand = Command.make("query", {
 	const clamped = clampTopK(topK);
 	if (clamped.clamped) yield* Effect.logDebug(`topK clamped from ${topK} to ${clamped.value}`);
 	const results = yield* QueryProject.queryProject(queryText, clamped.value);
-	if (json) return yield* Effect.sync(() => {
+	if (json) {
 		const output = results.map((r) => ({
 			score: r.score,
 			file: r.file,
@@ -224,17 +230,31 @@ const queryCommand = Command.make("query", {
 			...ctxLines > 0 && r.contextBefore && { contextBefore: r.contextBefore },
 			...ctxLines > 0 && r.contextAfter && { contextAfter: r.contextAfter }
 		}));
-		console.log(JSON.stringify(output, null, 2));
-	});
+		return yield* Console.log(JSON.stringify(output, null, 2));
+	}
 	if (results.length === 0) {
 		yield* Effect.logInfo("No results found");
 		return;
 	}
-	for (const result of results) yield* Effect.sync(() => {
-		console.log(formatResult(result));
-		console.log("---");
-	});
-}));
+	for (const result of results) {
+		yield* Console.log(formatResult(result));
+		yield* Console.log("---");
+	}
+}).pipe(Effect.tapError((error) => Console.log(formatError(error)))));
+//#endregion
+//#region src/lib/format.ts
+/** Format byte count as human-readable string (e.g. "1.5 MB") */
+const formatBytes = (bytes) => {
+	if (bytes === 0) return "0 B";
+	const units = [
+		"B",
+		"KB",
+		"MB",
+		"GB"
+	];
+	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
+	return `${(bytes / 1024 ** i).toFixed(1)} ${units[i]}`;
+};
 //#endregion
 //#region src/commands/reset.ts
 /** CLI command: pix reset [--json] */
@@ -242,15 +262,13 @@ const resetCommand = Command.make("reset", { json: Options.boolean("json").pipe(
 	const start = yield* Clock.currentTimeMillis;
 	const result = yield* ResetIndex.reset();
 	const elapsedMs = (yield* Clock.currentTimeMillis) - start;
-	if (json) return yield* Effect.sync(() => {
-		console.log(JSON.stringify({
-			status: "ok",
-			deletedChunks: result.deletedChunks,
-			deletedVectors: result.deletedVectors,
-			freedBytes: result.freedBytes,
-			elapsedMs
-		}));
-	});
+	if (json) return yield* Console.log(JSON.stringify({
+		status: "ok",
+		deletedChunks: result.deletedChunks,
+		deletedVectors: result.deletedVectors,
+		freedBytes: result.freedBytes,
+		elapsedMs
+	}));
 	if (!result.deletedChunks && !result.deletedVectors) {
 		yield* Effect.logInfo("Nothing to reset.");
 		return;
@@ -259,48 +277,22 @@ const resetCommand = Command.make("reset", { json: Options.boolean("json").pipe(
 	if (result.deletedChunks) parts.push("chunks.jsonl");
 	if (result.deletedVectors) parts.push("vectors.bin");
 	yield* Effect.logInfo(`Deleted: ${parts.join(", ")}`);
-	yield* Effect.logInfo(`Freed: ${formatBytes$1(result.freedBytes)}`);
+	yield* Effect.logInfo(`Freed: ${formatBytes(result.freedBytes)}`);
 	yield* Effect.logInfo(`Time: ${elapsedMs}ms`);
-}));
-/** Format byte count as human-readable string (e.g. "1.5 MB") */
-const formatBytes$1 = (bytes) => {
-	if (bytes === 0) return "0 B";
-	const units = [
-		"B",
-		"KB",
-		"MB",
-		"GB"
-	];
-	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
-	return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
-};
+}).pipe(Effect.tapError((error) => Console.log(formatError(error)))));
 //#endregion
 //#region src/commands/status.ts
 /** CLI command: pix status [--json] */
 const statusCommand = Command.make("status", { json: Options.boolean("json").pipe(Options.withDefault(false)) }, ({ json }) => Effect.gen(function* () {
 	const result = yield* GetStatus.getStatus();
-	if (json) return yield* Effect.sync(() => {
-		console.log(JSON.stringify(result, null, 2));
-	});
+	if (json) return yield* Console.log(JSON.stringify(result, null, 2));
 	const lastIndexStr = result.lastIndex > 0 ? new Date(result.lastIndex).toISOString() : "never";
 	yield* Effect.logInfo(`Indexed: ${result.chunks} chunks across ${result.files} files`);
 	yield* Effect.logInfo(`Model: ${result.model || "none"}`);
 	yield* Effect.logInfo(`Total lines: ${result.totalLines.toLocaleString()}`);
 	yield* Effect.logInfo(`Index size: ${formatBytes(result.byteSize)}`);
 	yield* Effect.logInfo(`Last indexed: ${lastIndexStr}`);
-}));
-/** Format byte count as human-readable string (e.g. "1.5 MB") */
-const formatBytes = (bytes) => {
-	if (bytes === 0) return "0 B";
-	const units = [
-		"B",
-		"KB",
-		"MB",
-		"GB"
-	];
-	const i = Math.min(Math.floor(Math.log(bytes) / Math.log(1024)), units.length - 1);
-	return `${(bytes / Math.pow(1024, i)).toFixed(1)} ${units[i]}`;
-};
+}).pipe(Effect.tapError((error) => Console.log(formatError(error)))));
 //#endregion
 //#region src/cli.ts
 const VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -314,10 +306,10 @@ const pix = Command.make("pix", {}, () => Effect.gen(function* () {
 	queryCommand,
 	resetCommand
 ]));
-const cli = Command.run(pix, {
+const cli = (args) => Command.run(pix, {
 	name: "pix",
 	version: VERSION
-});
+})(args).pipe(Effect.provide(CliConfig.layer({ showTypes: false })));
 //#endregion
 //#region src/services/chunker.ts
 const MIN_CHUNK_CHARS = 20;
@@ -451,9 +443,16 @@ const make$2 = Effect.gen(function* () {
 const OnnxEmbedderLive = Layer.effect(Embedder, make$2);
 //#endregion
 //#region src/services/scanner.ts
+const ALWAYS_IGNORE = new Set([
+	".pix",
+	"node_modules",
+	".git",
+	"dist",
+	"build",
+	".next"
+]);
 const make$1 = Effect.gen(function* () {
 	const fs = yield* FileSystem.FileSystem;
-	/** Loads all gitignore patterns from .gitignore files in the repo. */
 	const loadGitignoreRules = Effect.gen(function* () {
 		const ig = ignore();
 		const cwd = process.cwd();
@@ -466,13 +465,30 @@ const make$1 = Effect.gen(function* () {
 		}
 		return ig;
 	}).pipe(Effect.catchAll(() => Effect.succeed(ignore())));
+	const walk = (dir, extensions) => Effect.gen(function* () {
+		const entries = yield* fs.readDirectory(dir).pipe(Effect.catchAll(() => Effect.succeed([])));
+		let results = [];
+		for (const entry of entries) {
+			if (ALWAYS_IGNORE.has(entry)) continue;
+			const fullPath = `${dir}/${entry}`;
+			const info = yield* fs.stat(fullPath).pipe(Effect.catchAll(() => Effect.succeed(null)));
+			if (!info) continue;
+			if (info.type === "Directory") {
+				const subResults = yield* walk(fullPath, extensions);
+				results.push(...subResults);
+			} else if (info.type === "File") {
+				const dotIndex = entry.lastIndexOf(".");
+				if (dotIndex === -1) continue;
+				const ext = entry.slice(dotIndex);
+				if (extensions.has(ext)) results.push(fullPath);
+			}
+		}
+		return results;
+	});
 	const scanFiles = (extensions) => Effect.gen(function* () {
 		const ig = yield* loadGitignoreRules;
 		const cwd = process.cwd();
-		const pattern = extensions.map((ext) => `**/*${ext}`);
-		const relativePaths = (yield* Effect.tryPromise(() => fg(pattern, { dot: false })).pipe(Effect.catchAll(() => Effect.succeed([])))).map((p) => {
-			return p.startsWith(cwd) ? p.slice(cwd.length + 1) : p;
-		});
+		const relativePaths = (yield* walk(cwd, new Set(extensions))).map((p) => p.startsWith(cwd) ? p.slice(cwd.length + 1) : p);
 		return ig.filter(relativePaths).map((p) => `${cwd}/${p}`);
 	});
 	return { scanFiles };
@@ -587,7 +603,7 @@ const make = Effect.gen(function* () {
 		const model = readModelFromChunks(lines);
 		const totalLines = countTotalLines(lines);
 		const vectorsStat = yield* fs.stat(VECTORS_FILE).pipe(Effect.catchAll(() => Effect.succeed(null)));
-		const byteSize = vectorsStat && "size" in vectorsStat ? vectorsStat.size : 0;
+		const byteSize = vectorsStat && "size" in vectorsStat ? Number(vectorsStat.size) : 0;
 		return {
 			chunks,
 			files,
@@ -603,13 +619,13 @@ const make = Effect.gen(function* () {
 		let freedBytes = 0;
 		if (yield* fs.exists(CHUNKS_FILE)) {
 			const stat = yield* fs.stat(CHUNKS_FILE);
-			freedBytes += stat && "size" in stat ? stat.size : 0;
+			freedBytes += stat && "size" in stat ? Number(stat.size) : 0;
 			yield* fs.remove(CHUNKS_FILE);
 			deletedChunks = true;
 		}
 		if (yield* fs.exists(VECTORS_FILE)) {
 			const stat = yield* fs.stat(VECTORS_FILE);
-			freedBytes += stat && "size" in stat ? stat.size : 0;
+			freedBytes += stat && "size" in stat ? Number(stat.size) : 0;
 			yield* fs.remove(VECTORS_FILE);
 			deletedVectors = true;
 		}
@@ -634,6 +650,6 @@ const ChunkerLayer = ChunkerLive.pipe(Layer.provide(ServicesLayer));
 const InfraLayer = Layer.mergeAll(ServicesLayer, ChunkerLayer).pipe(Layer.provide(NodeContext.layer));
 const UseCaseLayer = Layer.mergeAll(InitProject.Default, GetStatus.Default, QueryProject.Default, IndexProject.Default, ResetIndex.Default);
 const AppLayer = Layer.merge(UseCaseLayer.pipe(Layer.provide(InfraLayer)), NodeContext.layer);
-cli(process.argv).pipe(Effect.provide(AppLayer), NodeRuntime.runMain);
+cli(process.argv).pipe(Effect.provide(AppLayer), NodeRuntime.runMain({ disableErrorReporting: true }));
 //#endregion
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lucas-bur/pix",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Lightweight local semantic project indexer",
   "keywords": [
     "cli",
@@ -39,8 +39,13 @@
     "test": "vp test",
     "test:coverage": "vp test --coverage",
     "check": "vp check",
-    "ci": "vp check && vp test --coverage && vp run build && fallow audit",
-    "lint:fallow": "fallow --format json",
+    "ci": "vp run check && vp run test:coverage && vp run build && vp run lint:effect && vp run lint:fallow",
+    "lint:effect": "effect-language-service diagnostics --project tsconfig.json --format pretty --strict",
+    "lint:effect:ci": "effect-language-service diagnostics --project tsconfig.json --format github-actions --strict",
+    "lint:effect:agent": "effect-language-service diagnostics --project tsconfig.json --format json --strict",
+    "lint:fallow": "fallow",
+    "lint:fallow:ci": "vpx fallow audit --base main --format badge",
+    "lint:fallow:agent": "fallow --format json",
     "fallow": "fallow",
     "prepublishOnly": "vp run build",
     "pix": ""
@@ -51,7 +56,6 @@
     "@effect/platform-node": "^0.106.0",
     "@huggingface/transformers": "^4.2.0",
     "effect": "^3.21.2",
-    "fast-glob": "^3.3.3",
     "ignore": "^7.0.5"
   },
   "devDependencies": {
@@ -59,6 +63,7 @@
     "@types/node": "^25.5.0",
     "@typescript/native-preview": "7.0.0-dev.20260328.1",
     "@vitest/coverage-v8": "^4.1.6",
+    "effect-memfs": "^0.8.0",
     "fallow": "^2.65.0",
     "typescript": "^6.0.2",
     "vite-plus": "^0.1.14"