@dotlabshq/clave 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,34 @@
-# Temporary Holding Version
+# @dotlabshq/clave
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Connect a repository to [clave](https://clave.one), the plan and work tracker for people and AI agents, in one command.
+
+```bash
+npx @dotlabshq/clave init
+```
+
+It runs in your terminal, in the repository:
+
+1. **Signs you in** through the browser (no token to copy). The sign-in lasts for this run only and is not saved.
+2. **Picks the org** (one where you are owner or admin) and **the project**: it matches this repository's git remote, or creates a project.
+3. **Picks or creates the unit** (team) your agents work for.
+4. **Registers your agents** (default `coder`) and issues one token for each.
+5. **Adds them to Claude Code** for this project (`claude mcp add --scope local`: stored on this machine, not in the repository). Without the `claude` CLI it writes `.mcp.json` with variable names only and the tokens to a git-ignored `.env.clave`.
+6. **Adds a clave block** to `AGENTS.md` or `CLAUDE.md` (it asks first), so every agent session starts with `session_start`.
+
+Tokens are never printed, so they never reach the chat or your AI agent's context.
+
+## Options
+
+| Option | |
+|---|---|
+| `--org <slug>` | Org to use (default: ask) |
+| `--project <key>` | Existing project key (default: match this repository) |
+| `--agents <a,b>` | Agent names, e.g. `coder,reviewer` (default: ask) |
+| `--yes` | Accept the defaults without asking |
+| `--no-open` | Print the sign-in link instead of opening the browser |
+| `--no-claude` | Write `.mcp.json` and `.env.clave` instead of using the `claude` CLI |
+| `--url <site>` | clave site (default `https://clave.one`, or `CLAVE_URL`) |
+
+Start Claude Code in the repository after `init`; servers added while a session is open load at the next session start.
+
+Guide for AI agents: https://clave.one/getting-started-ai.md

package/bin/clave.mjs

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+// clave CLI: `clave init` bu repoyu clave'e bağlar (giriş, proje, agent'lar, MCP ayarı).
+import { readFileSync } from "node:fs";
+import { init } from "../src/init.mjs";
+
+const args = process.argv.slice(2);
+const flag = (name) => { const i = args.indexOf(`--${name}`); return i >= 0 ? args[i + 1] : undefined; };
+const has = (name) => args.includes(`--${name}`);
+const version = JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+
+const help = `clave ${version}: connect this repository to clave (https://clave.one)
+
+Usage: npx @dotlabshq/clave init [options]
+
+  Signs you in through the browser, picks the org and project, registers your
+  agents, issues their tokens and adds them to Claude Code for this project.
+  Tokens are never printed.
+
+Options:
+  --org <slug>          Org to use (default: ask)
+  --project <key>       Existing project key (default: match this repository)
+  --agents <a,b>        Agent names (default: ask; "coder")
+  --yes                 Accept the defaults without asking
+  --no-open             Don't open the browser; print the sign-in link only
+  --no-claude           Don't use the claude CLI; write .mcp.json and .env.clave
+  --url <site>          clave site (default: https://clave.one)
+  -h, --help            This help
+  -v, --version         The version`;
+
+if (has("help") || args.includes("-h") || args.length === 0) { console.log(help); process.exit(0); }
+if (has("version") || args.includes("-v")) { console.log(version); process.exit(0); }
+if (args[0] !== "init") { console.error(`Unknown command: ${args[0]}\n\n${help}`); process.exit(2); }
+
+init({
+  site: flag("url") ?? process.env.CLAVE_URL ?? "https://clave.one",
+  org: flag("org"), project: flag("project"), agents: flag("agents"),
+  yes: has("yes"), open: !has("no-open"), claude: has("no-claude") ? "never" : "auto",
+}).catch((e) => { console.error(`clave: ${e.message}`); process.exit(1); });

package/package.json

@@ -1,6 +1,7 @@
-{
-  "name": "@dotlabshq/clave",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{ "name": "@dotlabshq/clave", "version": "0.1.0", "type": "module",
+  "description": "Set up clave (clave.one) in a repository: sign in, project, agents and MCP config for Claude Code in one command.",
+  "license": "MIT", "homepage": "https://clave.one/docs/getting-started-ai",
+  "bin": { "clave": "bin/clave.mjs" },
+  "files": ["bin", "src", "README.md"],
+  "engines": { "node": ">=18" },
+  "scripts": { "test": "node --test test/*.test.mjs", "typecheck": "node --check bin/clave.mjs && for f in src/*.mjs; do node --check $f || exit 1; done" } }

package/src/agentsmd.mjs

@@ -0,0 +1,32 @@
+// AGENTS.md / CLAUDE.md'ye clave bloğu: her oturum aynı başlasın. Varsa blok yenilenir.
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+
+const START = "<!-- clave:start -->", END = "<!-- clave:end -->";
+
+export function block({ project, servers, site }) {
+  return `${START}
+## Task management: clave
+
+- clave project: ${project}
+- MCP server${servers.length > 1 ? "s" : ""}: ${servers.map((s) => `\`${s}\``).join(", ")} (${site}/v1/mcp). Setup guide: ${site}/getting-started-ai.md
+- Start every session with \`session_start { project: "${project}" }\`: read the brief, the rules (binding) and the gotchas.
+- Before starting work, find or create its item in clave; claim it, report progress, finish with evidence.
+- Ask before risky steps with \`request_approval\` (production, deletes, external publishing). Leave what the next session needs with \`remember\`.
+${END}
+`;
+}
+
+/** Hangi dosya: CLAUDE.md varsa o, yoksa AGENTS.md (yoksa oluşturulur). */
+export function targetFile(cwd) {
+  for (const f of ["AGENTS.md", "CLAUDE.md"]) if (existsSync(join(cwd, f))) return join(cwd, f);
+  return join(cwd, "AGENTS.md");
+}
+
+export function upsert(path, text) {
+  const old = existsSync(path) ? readFileSync(path, "utf8") : "";
+  const i = old.indexOf(START), j = old.indexOf(END);
+  const next = i >= 0 && j > i ? old.slice(0, i) + text.trimEnd() + old.slice(j + END.length) : `${old}${old && !old.endsWith("\n\n") ? (old.endsWith("\n") ? "\n" : "\n\n") : ""}${text}`;
+  writeFileSync(path, next);
+  return old ? "updated" : "created";
+}

package/src/config.mjs

@@ -0,0 +1,44 @@
+// MCP ayarını yazar; secret ekrana ve modele hiç gelmez.
+// Claude Code varsa: `claude mcp add --scope local` (bu makinedeki proje ayarı, repoya girmez).
+// Yoksa: .mcp.json yalnız değişken adlarıyla (commit edilebilir) + git'e girmeyen .env.clave (0600).
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, chmodSync, appendFileSync } from "node:fs";
+import { join } from "node:path";
+
+export const envName = (agent) => `CLAVE_TOKEN_${agent.toUpperCase().replace(/[^A-Z0-9]/g, "_")}`;
+export const serverName = (agent) => `clave-${agent}`;
+
+export function hasClaude(run = spawnSync) {
+  const r = run("claude", ["--version"], { stdio: "ignore" });
+  return !r.error && r.status === 0;
+}
+
+/** Claude Code'a ekler; aynı adlı eski kayıt varsa önce siler. */
+export function addToClaude({ agent, mcpUrl, secret, cwd, run = spawnSync }) {
+  const name = serverName(agent);
+  run("claude", ["mcp", "remove", "--scope", "local", name], { cwd, stdio: "ignore" });
+  const r = run("claude", ["mcp", "add", "--scope", "local", "--transport", "http", name, mcpUrl, "--header", `Authorization: Bearer ${secret}`], { cwd, stdio: "ignore" });
+  if (r.error || r.status !== 0) throw new Error(`claude mcp add ${name} failed`);
+  return name;
+}
+
+/** Claude olmadan: .mcp.json (değişken adı) ve .env.clave (secret), .gitignore'a .env.clave. */
+export function writeFiles({ agents, mcpUrl, cwd }) {
+  const mcpPath = join(cwd, ".mcp.json");
+  const cfg = existsSync(mcpPath) ? JSON.parse(readFileSync(mcpPath, "utf8")) : {};
+  cfg.mcpServers ??= {};
+  for (const { agent } of agents) {
+    cfg.mcpServers[serverName(agent)] = { type: "http", url: mcpUrl, headers: { Authorization: `Bearer \${${envName(agent)}}` } };
+  }
+  writeFileSync(mcpPath, JSON.stringify(cfg, null, 2) + "\n");
+
+  const envPath = join(cwd, ".env.clave");
+  const old = existsSync(envPath) ? readFileSync(envPath, "utf8").split("\n").filter((l) => l && !agents.some((a) => l.startsWith(`${envName(a.agent)}=`))) : [];
+  writeFileSync(envPath, [...old, ...agents.map((a) => `${envName(a.agent)}=${a.secret}`)].join("\n") + "\n");
+  chmodSync(envPath, 0o600);
+
+  const gi = join(cwd, ".gitignore");
+  const lines = existsSync(gi) ? readFileSync(gi, "utf8").split("\n") : [];
+  if (!lines.includes(".env.clave")) appendFileSync(gi, `${lines.length && lines[lines.length - 1] !== "" ? "\n" : ""}.env.clave\n`);
+  return { mcpPath, envPath };
+}

package/src/http.mjs

@@ -0,0 +1,23 @@
+// clave'in REST'i: site adresi + /v1/mcp (Flect önek siler; yerelde web aynı yolu API'ye geçirir).
+// Kimlik cihaz akışından gelen kişi token'ı; org'a bağlı çağrılar X-Org-Id ile gider.
+
+export class ApiError extends Error {
+  constructor(status, code, message) { super(message || code); this.status = status; this.code = code; }
+}
+
+export function urls(site) {
+  const base = site.replace(/\/+$/, "");
+  return { site: base, api: `${base}/v1/mcp`, auth: `${base}/v1/auth`, mcp: `${base}/v1/mcp` };
+}
+
+export function client({ api, token, org = null, fetchImpl = fetch }) {
+  return async function call(method, path, body) {
+    const headers = { authorization: `Bearer ${token}`, accept: "application/json" };
+    if (org) headers["x-org-id"] = org;
+    if (body !== undefined) headers["content-type"] = "application/json";
+    const r = await fetchImpl(`${api}${path}`, { method, headers, ...(body !== undefined ? { body: JSON.stringify(body) } : {}) });
+    const data = await r.json().catch(() => ({}));
+    if (!r.ok) throw new ApiError(r.status, data.error ?? `http_${r.status}`, data.message ?? data.error);
+    return data;
+  };
+}

package/src/init.mjs

@@ -0,0 +1,118 @@
+// `clave init`: bu repo için clave kurulumu, kişinin kendi kimliğiyle (cihaz girişi):
+// org → proje → birim → agent'lar ve token'ları → MCP ayarı → AGENTS.md. Token'lar ekrana basılmaz.
+import { spawnSync } from "node:child_process";
+import { hostname } from "node:os";
+import { basename } from "node:path";
+import { client, urls } from "./http.mjs";
+import { deviceLogin, openBrowser } from "./login.mjs";
+import { prompter } from "./prompt.mjs";
+import { addToClaude, hasClaude, serverName, writeFiles, envName } from "./config.mjs";
+import { block, targetFile, upsert } from "./agentsmd.mjs";
+
+const NAME = /^[a-z0-9][a-z0-9-]{1,31}$/;
+
+/** git remote → "github.com/owner/repo"; remote yoksa klasör adı. */
+export function repoOf(cwd, run = spawnSync) {
+  const r = run("git", ["config", "--get", "remote.origin.url"], { cwd, encoding: "utf8" });
+  const raw = !r.error && r.status === 0 ? String(r.stdout).trim() : "";
+  const m = raw.match(/^(?:https?:\/\/|ssh:\/\/)?(?:[^@/]+@)?([^/:]+)[/:](.+?)(?:\.git)?\/?$/);
+  return { remote: m ? `${m[1]}/${m[2]}` : "", name: m ? basename(m[2]) : basename(cwd) };
+}
+
+export function matchProject(projects, repo) {
+  const live = projects.filter((p) => !p.archived);
+  const norm = (s) => String(s ?? "").toLowerCase().replace(/\.git$/, "").replace(/\/+$/, "");
+  return live.find((p) => repo.remote && p.repo && (norm(repo.remote).endsWith(norm(p.repo)) || norm(p.repo).endsWith(norm(repo.remote))))
+    ?? live.find((p) => p.key === repo.name.toLowerCase() || norm(p.name) === norm(repo.name)) ?? null;
+}
+
+export async function init(opts) {
+  const { site = "https://clave.one", cwd = process.cwd(), yes = false, open = true, claude: useClaude = "auto",
+    log = (s) => console.log(s), fetchImpl = fetch, run = spawnSync, loginInterval } = opts;
+  const u = urls(site);
+  const ask = opts.prompter ?? prompter({ yes });
+  try {
+    // 1. Giriş
+    const token = opts.token ?? await deviceLogin({ auth: u.auth, log, open: open ? openBrowser : null, fetchImpl, ...(loginInterval ? { interval: loginInterval } : {}) });
+    const me = client({ api: u.api, token, fetchImpl });
+
+    // 2. Org
+    const { orgs } = await me("GET", "/orgs");
+    const editable = orgs.filter((o) => o.role === "owner" || o.role === "admin");
+    if (editable.length === 0) throw new Error(orgs.length ? "You are not an owner or admin of any org; ask one to run this." : `You have no org yet. Create one at ${u.site}/start, then run this again.`);
+    const pick = opts.org ? editable.find((o) => o.slug === opts.org || o.id === opts.org) : null;
+    if (opts.org && !pick) throw new Error(`No org "${opts.org}" where you are owner or admin.`);
+    const org = pick ?? await ask.choose("Org", editable.map((o) => ({ label: `${o.name} (${o.slug})`, ...o })));
+    const call = client({ api: u.api, token, org: org.slug, fetchImpl });
+    log(`Org: ${org.name}`);
+
+    // 3. Proje
+    const setup = await call("GET", "/setup");
+    const repo = repoOf(cwd, run);
+    let project = opts.project ? setup.projects.find((p) => p.key === opts.project) : matchProject(setup.projects, repo);
+    if (opts.project && !project) throw new Error(`No project "${opts.project}" in ${org.name}.`);
+    if (project && !opts.project && !(await ask.confirm(`Use project "${project.name}" (${project.key})?`, true))) project = null;
+    if (!project) {
+      const name = await ask.ask("New project name", repo.name);
+      const lines = setup.lines.filter((l) => !l.archived);
+      const { key } = await call("POST", "/setup/projects", { name, repo: repo.remote, line: lines[0]?.key ?? "" });
+      project = { key, name };
+      log(`Project created: ${name} (${key})`);
+    } else log(`Project: ${project.name} (${project.key})`);
+
+    // 4. Birim
+    const units = setup.units.filter((x) => !x.archived);
+    let unit;
+    if (units.length) {
+      const pickU = await ask.choose("Unit the agents work for", units.map((x) => ({ label: x.name, ...x })));
+      unit = pickU.key;
+      log(`Unit: ${pickU.name}`);
+    }
+    else {
+      const name = await ask.ask("No units yet. Name the team that owns the work", "Core team");
+      unit = (await call("POST", "/setup/units", { name })).key;
+      log(`Unit created: ${name}`);
+    }
+    if (!setup.lines.some((l) => !l.archived) || !setup.goals.some((g) => !g.archived)) {
+      log(`Tip: the plan has no business line or goal yet. Finish it at ${u.site}/app/welcome`);
+    }
+
+    // 5. Agent'lar ve token'lar
+    const wanted = (opts.agents ?? await ask.ask("Agents to set up (comma-separated)", "coder")).split(",").map((s) => s.trim().toLowerCase()).filter(Boolean);
+    const bad = wanted.find((n) => !NAME.test(n));
+    if (bad) throw new Error(`"${bad}" is not a valid agent name: 2–32 lowercase letters, digits, dashes.`);
+    const { agents: existing } = await call("GET", "/agents");
+    const issued = [];
+    for (const agent of wanted) {
+      if (!existing.some((a) => a.name === agent)) { await call("POST", "/agents", { name: agent, unit }); log(`Agent registered: ${agent}`); }
+      const { secret } = await call("POST", `/agents/${encodeURIComponent(agent)}/tokens`, { label: hostname().slice(0, 30) });
+      issued.push({ agent, secret });
+    }
+
+    // 6. MCP ayarı
+    const claudeOk = useClaude === "never" ? false : useClaude === "always" ? true : hasClaude(run);
+    let servers;
+    if (claudeOk) {
+      servers = issued.map(({ agent, secret }) => addToClaude({ agent, mcpUrl: u.mcp, secret, cwd, run }));
+      log(`Claude Code: added ${servers.join(", ")} for this project (local scope; not in the repository).`);
+    } else {
+      const { mcpPath, envPath } = writeFiles({ agents: issued, mcpUrl: u.mcp, cwd });
+      servers = issued.map(({ agent }) => serverName(agent));
+      log(`Wrote ${basename(mcpPath)} (variable names only) and ${basename(envPath)} (tokens, git-ignored). Load it before starting your client: set -a; . ./.env.clave; set +a`);
+      log(`Codex: add [mcp_servers.${servers[0]}] url = "${u.mcp}", bearer_token_env_var = "${envName(issued[0].agent)}" to ~/.codex/config.toml`);
+    }
+    issued.forEach((x) => { x.secret = ""; });
+
+    // 7. AGENTS.md
+    const file = targetFile(cwd);
+    if (await ask.confirm(`Add the clave block to ${basename(file)}?`, true)) {
+      const how = upsert(file, block({ project: project.key, servers, site: u.site }));
+      log(`${basename(file)} ${how}.`);
+    }
+
+    log(`\nDone. Start your agent in this repository; its first call is session_start { project: "${project.key}" }.`);
+    return { org: org.slug, project: project.key, unit, agents: wanted, servers, claude: claudeOk };
+  } finally {
+    ask.close?.();
+  }
+}

package/src/login.mjs

@@ -0,0 +1,25 @@
+// Tarayıcıyla giriş: auth-service'in CLI cihaz akışı. /start bir onay adresi verir, kişi tarayıcıda clave'e
+// girip onaylar, /poll kişi token'ını döner (24 saat). Token yalnız bellekte tutulur, diske yazılmaz.
+import { spawn } from "node:child_process";
+
+export function openBrowser(url) {
+  const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
+  const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
+  try { spawn(cmd, args, { stdio: "ignore", detached: true }).unref(); return true; } catch { return false; }
+}
+
+export async function deviceLogin({ auth, log, open = openBrowser, fetchImpl = fetch, interval = 2000, timeout = 600_000 }) {
+  const r = await fetchImpl(`${auth}/start`);
+  if (!r.ok) throw new Error(`Sign-in could not start (HTTP ${r.status})`);
+  const { state, url } = await r.json();
+  log(`Sign in to clave in your browser:\n  ${url}`);
+  if (open) open(url);
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    await new Promise((res) => setTimeout(res, interval));
+    const p = await fetchImpl(`${auth}/poll/${encodeURIComponent(state)}`).then((x) => x.json()).catch(() => ({ status: "pending" }));
+    if (p.status === "done" && p.token) return p.token;
+    if (p.status === "expired") throw new Error("The sign-in link expired. Run the command again.");
+  }
+  throw new Error("Timed out waiting for the sign-in.");
+}

package/src/prompt.mjs

@@ -0,0 +1,31 @@
+// Soru-cevap: --yes ile varsayılanlar, yoksa terminalden.
+import { createInterface } from "node:readline/promises";
+import { stdin, stdout } from "node:process";
+
+export function prompter({ yes = false, input = stdin, output = stdout } = {}) {
+  let rl = null;
+  const line = async (q) => {
+    rl ??= createInterface({ input, output });
+    return (await rl.question(q)).trim();
+  };
+  return {
+    async ask(q, def = "") {
+      if (yes) return def;
+      const a = await line(def ? `${q} [${def}]: ` : `${q}: `);
+      return a || def;
+    },
+    async confirm(q, def = true) {
+      if (yes) return def;
+      const a = (await line(`${q} [${def ? "Y/n" : "y/N"}]: `)).toLowerCase();
+      return a ? a.startsWith("y") : def;
+    },
+    async choose(q, options, defIndex = 0) {
+      if (yes || options.length === 1) return options[defIndex];
+      options.forEach((o, i) => output.write(`  ${i + 1}) ${o.label}\n`));
+      const a = await line(`${q} [${defIndex + 1}]: `);
+      const n = Number(a || defIndex + 1);
+      return options[Number.isInteger(n) && n >= 1 && n <= options.length ? n - 1 : defIndex];
+    },
+    close() { rl?.close(); },
+  };
+}