@residue/cli 0.0.2 → 0.0.3

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @residue/cli
 
+## 0.0.3
+
+### Patch Changes
+
+- Add status command, common workflows docs, versioning policy.
+
 ## 0.0.2
 
 ### Patch Changes

package/dist/index.js

@@ -4450,9 +4450,144 @@ function setup(opts) {
   });
 }
 
+// src/commands/status.ts
+import { readFile as readFile4, stat as stat5 } from "fs/promises";
+import { join as join6 } from "path";
+var log9 = createLogger("status");
+function checkFileExists(path) {
+  return ResultAsync.fromPromise(stat5(path).then(() => true), toCliError({ message: "Failed to check file", code: "IO_ERROR" })).orElse(() => okAsync(false));
+}
+function checkHookInstalled(opts) {
+  const hookPath = join6(opts.gitDir, "hooks", opts.hookName);
+  return ResultAsync.fromPromise(readFile4(hookPath, "utf-8").then((content) => content.includes(opts.needle)), toCliError({ message: "Failed to read hook", code: "IO_ERROR" })).orElse(() => okAsync(false));
+}
+function getGitDir() {
+  return ResultAsync.fromPromise((async () => {
+    const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+      stdout: "pipe",
+      stderr: "pipe"
+    });
+    await proc.exited;
+    return (await new Response(proc.stdout).text()).trim();
+  })(), toCliError({ message: "Failed to get git directory", code: "GIT_ERROR" }));
+}
+function status() {
+  return safeTry(async function* () {
+    const isRepo = yield* isGitRepo();
+    if (!isRepo) {
+      log9.info("Not a git repository.");
+      return ok(undefined);
+    }
+    const projectRoot = yield* getProjectRoot();
+    log9.info("Login");
+    const globalConfig = yield* readConfig();
+    if (globalConfig) {
+      log9.info(`  global: ${globalConfig.worker_url}`);
+    } else {
+      log9.info("  global: not configured");
+    }
+    const localConfig = yield* readLocalConfig(projectRoot);
+    if (localConfig) {
+      log9.info(`  local:  ${localConfig.worker_url}`);
+    } else {
+      log9.info("  local:  not configured");
+    }
+    const isActiveConfig = localConfig ?? globalConfig;
+    if (isActiveConfig) {
+      log9.info(`  active: ${isActiveConfig.worker_url}`);
+    } else {
+      log9.info('  active: none (run "residue login" to configure)');
+    }
+    log9.info("");
+    log9.info("Hooks");
+    const gitDir = yield* getGitDir();
+    const isPostCommitInstalled = yield* checkHookInstalled({
+      gitDir,
+      hookName: "post-commit",
+      needle: "residue capture"
+    });
+    log9.info(`  post-commit: ${isPostCommitInstalled ? "installed" : "not installed"}`);
+    const isPrePushInstalled = yield* checkHookInstalled({
+      gitDir,
+      hookName: "pre-push",
+      needle: "residue sync"
+    });
+    log9.info(`  pre-push:    ${isPrePushInstalled ? "installed" : "not installed"}`);
+    if (!isPostCommitInstalled || !isPrePushInstalled) {
+      log9.info('  run "residue init" to install missing hooks');
+    }
+    log9.info("");
+    log9.info("Adapters");
+    const isClaudeSetup = yield* checkFileExists(join6(projectRoot, ".claude", "settings.json"));
+    let isClaudeHookConfigured = false;
+    if (isClaudeSetup) {
+      isClaudeHookConfigured = yield* ResultAsync.fromPromise(readFile4(join6(projectRoot, ".claude", "settings.json"), "utf-8").then((content) => content.includes("residue hook claude-code")), toCliError({
+        message: "Failed to read claude settings",
+        code: "IO_ERROR"
+      })).orElse(() => okAsync(false));
+    }
+    log9.info(`  claude-code: ${isClaudeHookConfigured ? "configured" : "not configured"}`);
+    const isPiSetup = yield* checkFileExists(join6(projectRoot, ".pi", "extensions", "residue.ts"));
+    log9.info(`  pi:          ${isPiSetup ? "configured" : "not configured"}`);
+    log9.info("");
+    log9.info("Sessions");
+    const pendingPath = yield* getPendingPath(projectRoot);
+    const sessions = yield* readPending(pendingPath);
+    if (sessions.length === 0) {
+      log9.info("  no pending sessions");
+    } else {
+      const openSessions = sessions.filter((s) => s.status === "open");
+      const endedSessions = sessions.filter((s) => s.status === "ended");
+      const totalCommits = sessions.reduce((sum, s) => sum + s.commits.length, 0);
+      const sessionsWithCommits = sessions.filter((s) => s.commits.length > 0);
+      log9.info(`  total:   ${sessions.length}`);
+      log9.info(`  open:    ${openSessions.length}`);
+      log9.info(`  ended:   ${endedSessions.length}`);
+      log9.info(`  commits: ${totalCommits} across ${sessionsWithCommits.length} session(s)`);
+      const isReadyToSync = sessionsWithCommits.length > 0;
+      if (isReadyToSync) {
+        log9.info(`  ${sessionsWithCommits.length} session(s) ready to sync on next push`);
+      } else {
+        log9.info("  no sessions ready to sync (no commits captured yet)");
+      }
+    }
+    return ok(undefined);
+  });
+}
+// package.json
+var package_default = {
+  name: "@residue/cli",
+  version: "0.0.3",
+  repository: {
+    type: "git",
+    url: "https://github.com/butttons/residue",
+    directory: "packages/cli"
+  },
+  type: "module",
+  bin: {
+    residue: "./dist/index.js"
+  },
+  scripts: {
+    dev: "bun run src/index.ts",
+    build: "bun build src/index.ts --outfile dist/index.js --target bun",
+    test: "bun test",
+    typecheck: "tsc --noEmit"
+  },
+  devDependencies: {
+    "@types/bun": "latest",
+    "@types/debug": "^4.1.12",
+    typescript: "^5.7.0"
+  },
+  dependencies: {
+    commander: "^14.0.3",
+    debug: "^4.4.3",
+    neverthrow: "^8.2.0"
+  }
+};
+
 // src/index.ts
 var program2 = new Command;
-program2.name("residue").description("Capture AI agent conversations linked to git commits").version("0.0.1");
+program2.name("residue").description("Capture AI agent conversations linked to git commits").version(package_default.version);
 program2.command("login").description("Save worker URL and auth token").requiredOption("--url <worker_url>", "Worker URL").requiredOption("--token <auth_token>", "Auth token").option("--local", "Save config to this project instead of globally").action(wrapCommand((opts) => login({ url: opts.url, token: opts.token, isLocal: opts.local })));
 program2.command("init").description("Install git hooks in current repo").action(wrapCommand(() => init()));
 program2.command("setup").description("Configure an agent adapter for this project").argument("<agent>", "Agent to set up (claude-code, pi)").action(wrapCommand((agent) => setup({ agent })));
@@ -4468,4 +4603,5 @@ session.command("end").description("Mark an agent session as ended").requiredOpt
 program2.command("capture").description("Tag pending sessions with current commit SHA (called by post-commit hook)").action(wrapHookCommand(() => capture()));
 program2.command("sync").description("Upload pending sessions to worker (called by pre-push hook)").option("--remote-url <url>", "Remote URL (passed by pre-push hook)").action(wrapHookCommand((opts) => sync({ remoteUrl: opts.remoteUrl })));
 program2.command("push").description("Upload pending sessions to worker (manual trigger)").action(wrapCommand(() => push()));
+program2.command("status").description("Show current residue state for this project").action(wrapCommand(() => status()));
 program2.parse();

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@residue/cli",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"repository": {
 		"type": "git",
 		"url": "https://github.com/butttons/residue",

package/src/commands/status.ts

@@ -0,0 +1,180 @@
+import { readFile, stat } from "fs/promises";
+import { ok, okAsync, ResultAsync, safeTry } from "neverthrow";
+import { join } from "path";
+import { readConfig, readLocalConfig } from "@/lib/config";
+import { isGitRepo } from "@/lib/git";
+import { getPendingPath, getProjectRoot, readPending } from "@/lib/pending";
+import type { CliError } from "@/utils/errors";
+import { toCliError } from "@/utils/errors";
+import { createLogger } from "@/utils/logger";
+
+const log = createLogger("status");
+
+function checkFileExists(path: string): ResultAsync<boolean, CliError> {
+	return ResultAsync.fromPromise(
+		stat(path).then(() => true),
+		toCliError({ message: "Failed to check file", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function checkHookInstalled(opts: {
+	gitDir: string;
+	hookName: string;
+	needle: string;
+}): ResultAsync<boolean, CliError> {
+	const hookPath = join(opts.gitDir, "hooks", opts.hookName);
+	return ResultAsync.fromPromise(
+		readFile(hookPath, "utf-8").then((content) =>
+			content.includes(opts.needle),
+		),
+		toCliError({ message: "Failed to read hook", code: "IO_ERROR" }),
+	).orElse(() => okAsync(false));
+}
+
+function getGitDir(): ResultAsync<string, CliError> {
+	return ResultAsync.fromPromise(
+		(async () => {
+			const proc = Bun.spawn(["git", "rev-parse", "--git-dir"], {
+				stdout: "pipe",
+				stderr: "pipe",
+			});
+			await proc.exited;
+			return (await new Response(proc.stdout).text()).trim();
+		})(),
+		toCliError({ message: "Failed to get git directory", code: "GIT_ERROR" }),
+	);
+}
+
+export function status(): ResultAsync<void, CliError> {
+	return safeTry(async function* () {
+		const isRepo = yield* isGitRepo();
+		if (!isRepo) {
+			log.info("Not a git repository.");
+			return ok(undefined);
+		}
+
+		const projectRoot = yield* getProjectRoot();
+
+		// -- Auth / Login state --
+		log.info("Login");
+
+		const globalConfig = yield* readConfig();
+		if (globalConfig) {
+			log.info(`  global: ${globalConfig.worker_url}`);
+		} else {
+			log.info("  global: not configured");
+		}
+
+		const localConfig = yield* readLocalConfig(projectRoot);
+		if (localConfig) {
+			log.info(`  local:  ${localConfig.worker_url}`);
+		} else {
+			log.info("  local:  not configured");
+		}
+
+		const isActiveConfig = localConfig ?? globalConfig;
+		if (isActiveConfig) {
+			log.info(`  active: ${isActiveConfig.worker_url}`);
+		} else {
+			log.info('  active: none (run "residue login" to configure)');
+		}
+
+		log.info("");
+
+		// -- Git hooks --
+		log.info("Hooks");
+
+		const gitDir = yield* getGitDir();
+
+		const isPostCommitInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "post-commit",
+			needle: "residue capture",
+		});
+		log.info(
+			`  post-commit: ${isPostCommitInstalled ? "installed" : "not installed"}`,
+		);
+
+		const isPrePushInstalled = yield* checkHookInstalled({
+			gitDir,
+			hookName: "pre-push",
+			needle: "residue sync",
+		});
+		log.info(
+			`  pre-push:    ${isPrePushInstalled ? "installed" : "not installed"}`,
+		);
+
+		if (!isPostCommitInstalled || !isPrePushInstalled) {
+			log.info('  run "residue init" to install missing hooks');
+		}
+
+		log.info("");
+
+		// -- Agent adapters --
+		log.info("Adapters");
+
+		const isClaudeSetup = yield* checkFileExists(
+			join(projectRoot, ".claude", "settings.json"),
+		);
+
+		let isClaudeHookConfigured = false;
+		if (isClaudeSetup) {
+			isClaudeHookConfigured = yield* ResultAsync.fromPromise(
+				readFile(join(projectRoot, ".claude", "settings.json"), "utf-8").then(
+					(content) => content.includes("residue hook claude-code"),
+				),
+				toCliError({
+					message: "Failed to read claude settings",
+					code: "IO_ERROR",
+				}),
+			).orElse(() => okAsync(false));
+		}
+
+		log.info(
+			`  claude-code: ${isClaudeHookConfigured ? "configured" : "not configured"}`,
+		);
+
+		const isPiSetup = yield* checkFileExists(
+			join(projectRoot, ".pi", "extensions", "residue.ts"),
+		);
+		log.info(`  pi:          ${isPiSetup ? "configured" : "not configured"}`);
+
+		log.info("");
+
+		// -- Pending sessions --
+		log.info("Sessions");
+
+		const pendingPath = yield* getPendingPath(projectRoot);
+		const sessions = yield* readPending(pendingPath);
+
+		if (sessions.length === 0) {
+			log.info("  no pending sessions");
+		} else {
+			const openSessions = sessions.filter((s) => s.status === "open");
+			const endedSessions = sessions.filter((s) => s.status === "ended");
+			const totalCommits = sessions.reduce(
+				(sum, s) => sum + s.commits.length,
+				0,
+			);
+			const sessionsWithCommits = sessions.filter((s) => s.commits.length > 0);
+
+			log.info(`  total:   ${sessions.length}`);
+			log.info(`  open:    ${openSessions.length}`);
+			log.info(`  ended:   ${endedSessions.length}`);
+			log.info(
+				`  commits: ${totalCommits} across ${sessionsWithCommits.length} session(s)`,
+			);
+
+			const isReadyToSync = sessionsWithCommits.length > 0;
+			if (isReadyToSync) {
+				log.info(
+					`  ${sessionsWithCommits.length} session(s) ready to sync on next push`,
+				);
+			} else {
+				log.info("  no sessions ready to sync (no commits captured yet)");
+			}
+		}
+
+		return ok(undefined);
+	});
+}

package/src/index.ts

@@ -9,15 +9,18 @@ import { push } from "@/commands/push";
 import { sessionEnd } from "@/commands/session-end";
 import { sessionStart } from "@/commands/session-start";
 import { setup } from "@/commands/setup";
+import { status } from "@/commands/status";
 import { sync } from "@/commands/sync";
 import { wrapCommand, wrapHookCommand } from "@/utils/errors";
 
+import packageJson from "../package.json";
+
 const program = new Command();
 
 program
 	.name("residue")
 	.description("Capture AI agent conversations linked to git commits")
-	.version("0.0.1");
+	.version(packageJson.version);
 
 program
 	.command("login")
@@ -97,4 +100,9 @@ program
 	.description("Upload pending sessions to worker (manual trigger)")
 	.action(wrapCommand(() => push()));
 
+program
+	.command("status")
+	.description("Show current residue state for this project")
+	.action(wrapCommand(() => status()));
+
 program.parse();