@lucas-bur/pix 0.3.0 → 0.4.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

@@ -2,7 +2,7 @@
 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 { Args, CliConfig, Command, Options } from "@effect/cli";
 import crypto from "node:crypto";
 import { FileSystem } from "@effect/platform";
 import { env } from "@huggingface/transformers";
@@ -68,15 +68,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 +133,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,18 +160,11 @@ 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({
@@ -163,7 +174,9 @@ const indexCommand = Command.make("index", {
 		}));
 	});
 	yield* Effect.logInfo(`Indexed ${result.right.stats.chunks} chunks from ${result.right.stats.files} files in ${duration}.`);
-}));
+}).pipe(Effect.tapError((error) => Effect.sync(() => {
+	console.log(formatError(error));
+}))));
 //#endregion
 //#region src/commands/init.ts
 /** CLI command: pix init [--json] */
@@ -174,7 +187,9 @@ const initCommand = Command.make("init", { json: Options.boolean("json").pipe(Op
 	});
 	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) => Effect.sync(() => {
+	console.log(formatError(error));
+}))));
 //#endregion
 //#region src/commands/query.ts
 const DEFAULT_TOP_K = 5;
@@ -234,7 +249,23 @@ const queryCommand = Command.make("query", {
 		console.log(formatResult(result));
 		console.log("---");
 	});
-}));
+}).pipe(Effect.tapError((error) => Effect.sync(() => {
+	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] */
@@ -259,21 +290,11 @@ 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) => Effect.sync(() => {
+	console.log(formatError(error));
+}))));
 //#endregion
 //#region src/commands/status.ts
 /** CLI command: pix status [--json] */
@@ -288,19 +309,9 @@ const statusCommand = Command.make("status", { json: Options.boolean("json").pip
 	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) => Effect.sync(() => {
+	console.log(formatError(error));
+}))));
 //#endregion
 //#region src/cli.ts
 const VERSION = createRequire(import.meta.url)("../package.json").version;
@@ -314,10 +325,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;
@@ -587,7 +598,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 +614,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 +645,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.4.0",
   "description": "Lightweight local semantic project indexer",
   "keywords": [
     "cli",
@@ -59,6 +59,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"