@hypercarrier/rarebit 0.1.0-alpha.1

package/src/rarebit-cli.mjs

@@ -0,0 +1,305 @@
+import { spawn } from "node:child_process";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { resolveRarebitSettings } from "./rarebit-settings.mjs";
+import {
+  processRarebitSummary,
+  processRarebitTitle,
+} from "./rarebit-service.mjs";
+import {
+  extractRarebits,
+  queryRarebits,
+  readRarebitSession,
+} from "./rarebit-session.mjs";
+
+export const RAREBIT_CLI_USAGE = `Usage:
+  rarebit query --session <exact-path-or-id> --json
+  rarebit extract --session <exact-path-or-id> --json
+  rarebit summarize --session <exact-path-or-id> [--force] [--model-command <executable> [--model-arg <arg>]] --json
+  rarebit title --session <exact-path-or-id> [--date YYYY-MM-DD] [--model-command <executable> [--model-arg <arg>]] --json
+
+Normal summarize/title resolve rarebit.model from Pi settings. The optional model-command
+adapter receives one prompt on stdin and must write only model text to stdout.
+query is metadata-only; extract exposes raw selected Rarebit prose on demand.`;
+
+function requiredValue(argv, index, flag) {
+  const value = argv[index + 1];
+  if (!value || value.startsWith("--"))
+    throw new Error(`${flag} requires a value`);
+  return value;
+}
+
+export function parseRarebitCliArgs(argv) {
+  if (argv.includes("--help") || argv.includes("-h")) return { help: true };
+  const [command, ...rest] = argv;
+  if (!new Set(["query", "extract", "summarize", "title"]).has(command))
+    throw new Error(
+      "First argument must be query, extract, summarize, or title",
+    );
+  const options = { command, modelArgs: [], json: false, force: false };
+  for (let index = 0; index < rest.length; index += 1) {
+    const argument = rest[index];
+    switch (argument) {
+      case "--session":
+        options.session = requiredValue(rest, index, argument);
+        index += 1;
+        break;
+      case "--model-command":
+        options.modelCommand = requiredValue(rest, index, argument);
+        index += 1;
+        break;
+      case "--model-arg":
+        options.modelArgs.push(requiredValue(rest, index, argument));
+        index += 1;
+        break;
+      case "--date":
+        options.date = requiredValue(rest, index, argument);
+        index += 1;
+        break;
+      case "--json":
+        options.json = true;
+        break;
+      case "--force":
+        options.force = true;
+        break;
+      default:
+        throw new Error(`Unknown argument: ${argument}`);
+    }
+  }
+  if (!options.session) throw new Error("--session is required");
+  if (!options.json) throw new Error("--json is required");
+  if (options.force && command !== "summarize")
+    throw new Error("--force only applies to summarize");
+  return options;
+}
+
+export function runModelCommand(
+  command,
+  args,
+  prompt,
+  { spawnProcess = spawn, env } = {},
+) {
+  return new Promise((resolve, reject) => {
+    const child = spawnProcess(command, args, {
+      stdio: ["pipe", "pipe", "pipe"],
+      shell: false,
+      env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.setEncoding("utf8");
+    child.stderr.setEncoding("utf8");
+    child.stdout.on("data", (chunk) => {
+      stdout += chunk;
+    });
+    child.stderr.on("data", (chunk) => {
+      stderr += chunk;
+    });
+    child.on("error", (error) =>
+      reject(
+        new Error(`Cannot start model command ${command}: ${error.message}`),
+      ),
+    );
+    child.on("close", (code, signal) => {
+      if (code === 0) return resolve(stdout);
+      const detail =
+        stderr.trim() ||
+        `exit ${code ?? "null"}${signal ? ` (${signal})` : ""}`;
+      reject(new Error(`Model command failed: ${detail}`));
+    });
+    child.stdin.end(prompt);
+  });
+}
+
+/**
+ * The normal CLI adapter deliberately invokes Pi in a stripped, ephemeral
+ * print mode. Pi—not this package—continues to own credentials, provider
+ * configuration, proxy behavior, and model transport.
+ */
+export function runPiRarebitModel({
+  model,
+  prompt,
+  agentDir,
+  piCommand = "pi",
+  spawnProcess = spawn,
+}) {
+  const args = [
+    "--print",
+    "--no-session",
+    "--no-tools",
+    "--no-extensions",
+    "--no-skills",
+    "--no-context-files",
+    "--no-prompt-templates",
+    "--model",
+    `${model.provider}/${model.id}`,
+    "--system-prompt",
+    "Return only the requested result. Do not use tools.",
+  ];
+  return runModelCommand(piCommand, args, prompt, {
+    spawnProcess,
+    env: {
+      ...process.env,
+      ...(agentDir ? { PI_CODING_AGENT_DIR: agentDir } : {}),
+    },
+  });
+}
+
+function configuredAgentDir(env = process.env) {
+  return env.PI_CODING_AGENT_DIR ?? join(homedir(), ".pi", "agent");
+}
+
+async function jsonFile(path) {
+  try {
+    return JSON.parse(await readFile(path, "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") return {};
+    throw new Error(`Cannot read Pi settings ${path}: ${error.message}`);
+  }
+}
+
+/** Read the narrow, explicit model/policy contract shared with the Pi shell. */
+export async function readRarebitCliSettings({
+  agentDir = configuredAgentDir(),
+  cwd = process.cwd(),
+} = {}) {
+  const globalPath = join(agentDir, "settings.json");
+  const projectPath = join(cwd, ".pi", "settings.json");
+  const resolved = resolveRarebitSettings(
+    await jsonFile(globalPath),
+    await jsonFile(projectPath),
+  );
+  if (!resolved.model)
+    throw new Error(
+      resolved.modelConfigurationError ??
+        "Rarebit model is not configured; set rarebit.model to provider/model in Pi settings",
+    );
+  return {
+    agentDir,
+    model: resolved.model,
+    modelProvenance: {
+      source: "pi_settings_files",
+      settingsKey: "rarebit.model",
+      status: "resolved",
+      rawRefs: [globalPath, projectPath],
+    },
+    summaryPolicy: resolved.summaryPolicy,
+    autoTitle: resolved.autoTitle,
+  };
+}
+
+function contextForLoadedSession(loaded) {
+  return {
+    sessionManager: {
+      getHeader: () => ({ id: loaded.session.id }),
+      getSessionFile: () => loaded.sessionFile,
+      getBranch: () => loaded.branch,
+    },
+  };
+}
+
+function sessionDate(session, explicitDate) {
+  if (explicitDate) return explicitDate;
+  const timestamp = session?.startedAt;
+  if (typeof timestamp === "string" && /^\d{4}-\d{2}-\d{2}/.test(timestamp))
+    return timestamp.slice(0, 10);
+  throw new Error(
+    "--date YYYY-MM-DD is required because the persisted Session has no ISO start date",
+  );
+}
+
+async function modelRuntime(options, dependencies) {
+  if (options.modelCommand) {
+    return {
+      model: { provider: "external-command", id: options.modelCommand },
+      modelProvenance: { source: "explicit_model_command", status: "resolved" },
+      summaryPolicy: {},
+      complete: (prompt) =>
+        dependencies.runModelCommand(
+          options.modelCommand,
+          options.modelArgs,
+          prompt,
+        ),
+    };
+  }
+  const settings = await dependencies.readSettings();
+  return {
+    ...settings,
+    complete: (prompt) =>
+      dependencies.runPiModel({
+        model: settings.model,
+        prompt,
+        agentDir: settings.agentDir,
+      }),
+  };
+}
+
+export async function runRarebitCli(options, dependencies = {}) {
+  const runtimeDependencies = {
+    readSettings: dependencies.readSettings ?? readRarebitCliSettings,
+    runPiModel: dependencies.runPiModel ?? runPiRarebitModel,
+    runModelCommand: dependencies.runModelCommand ?? runModelCommand,
+    processSummary: dependencies.processSummary ?? processRarebitSummary,
+    processTitle: dependencies.processTitle ?? processRarebitTitle,
+  };
+  if (options.command === "query") return queryRarebits(options.session);
+  if (options.command === "extract") return extractRarebits(options.session);
+
+  const loaded = await readRarebitSession(options.session);
+  const runtime = await modelRuntime(options, runtimeDependencies);
+  if (options.command === "summarize") {
+    const result = await runtimeDependencies.processSummary(
+      contextForLoadedSession(loaded),
+      {
+        model: runtime.model,
+        modelProvenance: runtime.modelProvenance,
+        summaryPolicy: runtime.summaryPolicy,
+        forceSynthesis: options.force === true,
+        allowExternalSession: true,
+        rarebitRoot: dependencies.rarebitRoot,
+        sessionRoot: dependencies.sessionRoot,
+        modelClient: {
+          complete: async ({ prompt }) => ({
+            text: await runtime.complete(prompt),
+          }),
+        },
+      },
+    );
+    return {
+      operation: "summary",
+      status: result.record.status,
+      duplicate: result.duplicate === true,
+      inFlight: result.inFlight === true,
+      record: result.record,
+    };
+  }
+
+  const result = await runtimeDependencies.processTitle(
+    contextForLoadedSession(loaded),
+    {
+      model: runtime.model,
+      modelProvenance: runtime.modelProvenance,
+      allowFirstUserFallback: true,
+      evidenceProvenance: "branch_user_fallback",
+      titleDate: sessionDate(loaded.session, options.date),
+      allowExternalSession: true,
+      rarebitRoot: dependencies.rarebitRoot,
+      sessionRoot: dependencies.sessionRoot,
+      modelClient: {
+        complete: async ({ prompt }) => ({
+          text: await runtime.complete(prompt),
+        }),
+      },
+    },
+  );
+  return {
+    operation: "title",
+    status: result.record.status,
+    duplicate: result.duplicate === true,
+    inFlight: result.inFlight === true,
+    session: loaded.session,
+    title: result.record.title,
+    record: result.record,
+  };
+}

package/src/rarebit-command.mjs

@@ -0,0 +1,281 @@
+const literal = (value, description) => ({
+  kind: "literal",
+  value,
+  description,
+});
+
+const number = (usage, validate) => ({
+  kind: "number",
+  usage,
+  validate,
+});
+
+const rest = (usage) => ({
+  kind: "rest",
+  usage,
+});
+
+export const RAREBIT_COMMAND_GRAMMAR = Object.freeze({
+  name: "rarebit",
+  defaultSubcommand: "status",
+  subcommands: Object.freeze([
+    {
+      name: "status",
+      description: "Show effective Rarebit configuration",
+      forms: [[]],
+    },
+    {
+      name: "recall",
+      description: "Recall active-branch Rarebit messages with a prompt",
+      forms: [[rest("<prompt...>")]],
+    },
+    {
+      name: "config",
+      description: "Show or override summary policy for this process",
+      forms: [
+        [],
+        [
+          literal(
+            "max_rarebit_ratio",
+            "Override the maximum selected-prose ratio",
+          ),
+          number("<0..1>", (value) => value >= 0 && value <= 1),
+        ],
+        [
+          literal(
+            "min_total_length",
+            "Override the minimum estimated token count",
+          ),
+          number("<nonnegative estimated tokens>", (value) => value >= 0),
+        ],
+      ],
+    },
+    {
+      name: "auto-title",
+      description: "Show or override automatic Session titles",
+      forms: [
+        [],
+        [literal("on", "Enable automatic Session titles")],
+        [literal("off", "Disable automatic Session titles")],
+      ],
+    },
+    {
+      name: "title",
+      description: "Generate a title for the active Session",
+      usageNote: "use Pi's native /name for a literal title",
+      forms: [[]],
+    },
+    {
+      name: "summarize",
+      description: "Force a Rarebit Summary materialization",
+      forms: [[]],
+    },
+  ]),
+});
+
+const renderToken = (token) =>
+  token.kind === "literal" ? token.value : token.usage;
+
+const renderForms = (forms) => {
+  const hasEmptyForm = forms.some((form) => form.length === 0);
+  const alternatives = forms
+    .filter((form) => form.length > 0)
+    .map((form) => form.map(renderToken).join(" "));
+  if (alternatives.length === 0) return "";
+  const rendered = alternatives.join("|");
+  return hasEmptyForm ? ` [${rendered}]` : ` ${rendered}`;
+};
+
+export function rarebitCommandDescription(grammar = RAREBIT_COMMAND_GRAMMAR) {
+  return `Rarebit ${grammar.subcommands.map(({ name }) => name).join("/")}`;
+}
+
+export function rarebitCommandUsage(
+  subcommand,
+  grammar = RAREBIT_COMMAND_GRAMMAR,
+) {
+  if (!subcommand) {
+    return `Usage: /${grammar.name} [${grammar.subcommands
+      .map(({ name }) => name)
+      .join("|")}]`;
+  }
+  const definition = grammar.subcommands.find(
+    ({ name }) => name === subcommand,
+  );
+  if (!definition) return rarebitCommandUsage(undefined, grammar);
+  const note = definition.usageNote ? ` (${definition.usageNote})` : "";
+  return `Usage: /${grammar.name} ${definition.name}${renderForms(definition.forms)}${note}`;
+}
+
+const matchToken = (definition, rawValue) => {
+  if (definition.kind === "literal") return rawValue === definition.value;
+  if (definition.kind === "rest") return String(rawValue).trim().length > 0;
+  const value = Number(rawValue);
+  return Number.isFinite(value) && definition.validate(value);
+};
+
+export function parseRarebitCommand(input, grammar = RAREBIT_COMMAND_GRAMMAR) {
+  const rawInput = String(input ?? "");
+  const tokens = rawInput.trim().split(/\s+/).filter(Boolean);
+  const subcommandName = tokens[0] ?? grammar.defaultSubcommand;
+  const definition = grammar.subcommands.find(
+    ({ name }) => name === subcommandName,
+  );
+  if (!definition) {
+    return {
+      ok: false,
+      error: "unknown_subcommand",
+      usage: rarebitCommandUsage(undefined, grammar),
+    };
+  }
+
+  const freeform = definition.forms.find(
+    (form) => form.at(-1)?.kind === "rest",
+  );
+  if (freeform) {
+    const prefix = freeform.slice(0, -1);
+    const leading = rawInput.trimStart();
+    const subcommandEnd = leading.search(/\s/);
+    const rawArguments = subcommandEnd < 0 ? "" : leading.slice(subcommandEnd);
+    let remaining = rawArguments;
+    const parsed = [];
+    let prefixMatches = true;
+    for (const token of prefix) {
+      const separator = remaining.match(/^\s+/)?.[0] ?? "";
+      remaining = remaining.slice(separator.length);
+      const value = remaining.match(/^\S+/)?.[0];
+      if (!value || !matchToken(token, value)) {
+        prefixMatches = false;
+        break;
+      }
+      parsed.push(value);
+      remaining = remaining.slice(value.length);
+    }
+    if (prefixMatches && /^\s/.test(remaining)) {
+      const prompt = remaining.slice(1);
+      if (matchToken(freeform.at(-1), prompt)) {
+        return {
+          ok: true,
+          subcommand: definition.name,
+          arguments: [...parsed, prompt],
+        };
+      }
+    }
+    return {
+      ok: false,
+      error: "invalid_arguments",
+      subcommand: definition.name,
+      usage: rarebitCommandUsage(definition.name, grammar),
+    };
+  }
+
+  const argumentTokens = tokens.slice(1);
+  const form = definition.forms.find(
+    (candidate) =>
+      candidate.length === argumentTokens.length &&
+      candidate.every((token, index) =>
+        matchToken(token, argumentTokens[index]),
+      ),
+  );
+  if (!form) {
+    const hasMatchingShape = definition.forms.some(
+      (candidate) =>
+        candidate.length === argumentTokens.length &&
+        candidate.every(
+          (token, index) =>
+            token.kind !== "literal" || token.value === argumentTokens[index],
+        ),
+    );
+    return {
+      ok: false,
+      error: hasMatchingShape ? "invalid_value" : "invalid_arguments",
+      subcommand: definition.name,
+      usage: rarebitCommandUsage(definition.name, grammar),
+    };
+  }
+
+  return {
+    ok: true,
+    subcommand: definition.name,
+    arguments: argumentTokens,
+  };
+}
+
+const completionItem = ({ value, label, description }) => ({
+  value,
+  label,
+  ...(description ? { description } : {}),
+});
+
+export function getRarebitArgumentCompletions(
+  prefix,
+  grammar = RAREBIT_COMMAND_GRAMMAR,
+) {
+  const input = String(prefix ?? "").trimStart();
+  const trailingWhitespace = /\s$/.test(input);
+  const tokens = input.trim().split(/\s+/).filter(Boolean);
+
+  if (tokens.length === 0) {
+    return grammar.subcommands.map((subcommand) =>
+      completionItem({
+        value: subcommand.name,
+        label: subcommand.name,
+        description: subcommand.description,
+      }),
+    );
+  }
+
+  if (tokens.length === 1 && !trailingWhitespace) {
+    const partial = tokens[0];
+    const matches = grammar.subcommands
+      .filter(({ name }) => name.startsWith(partial))
+      .map((subcommand) =>
+        completionItem({
+          value: subcommand.name,
+          label: subcommand.name,
+          description: subcommand.description,
+        }),
+      );
+    return matches.length > 0 ? matches : null;
+  }
+
+  const definition = grammar.subcommands.find(({ name }) => name === tokens[0]);
+  if (!definition) return null;
+
+  const argumentTokens = tokens.slice(1);
+  const completionIndex = trailingWhitespace
+    ? argumentTokens.length
+    : argumentTokens.length - 1;
+  const partial = trailingWhitespace ? "" : argumentTokens.at(-1);
+  const priorArguments = argumentTokens.slice(0, completionIndex);
+  const matches = [];
+  const seen = new Set();
+
+  for (const form of definition.forms) {
+    const priorMatches = priorArguments.every(
+      (value, index) => form[index] && matchToken(form[index], value),
+    );
+    const token = form[completionIndex];
+    if (
+      !priorMatches ||
+      token?.kind !== "literal" ||
+      !token.value.startsWith(partial)
+    )
+      continue;
+
+    const needsFollowingArgument = form.length > completionIndex + 1;
+    const value = [definition.name, ...priorArguments, token.value].join(" ");
+    const completedValue = needsFollowingArgument ? `${value} ` : value;
+    if (seen.has(completedValue)) continue;
+    seen.add(completedValue);
+    matches.push(
+      completionItem({
+        value: completedValue,
+        label: token.value,
+        description: token.description,
+      }),
+    );
+  }
+
+  return matches.length > 0 ? matches : null;
+}