codiedev 0.3.3 → 0.3.5

package/dist/cli.js

@@ -22,9 +22,14 @@ const ping_1 = require("./commands/ping");
 const inbox_1 = require("./commands/inbox");
 const note_1 = require("./commands/note");
 const promote_1 = require("./commands/promote");
+const reverseTicket_1 = require("./commands/reverseTicket");
 const HELP = `
 CodieDev CLI
 
+  The team artifact layer for agent-coded work. Share specs and reviews
+  with teammates, get pinged when they need your input, pick up where
+  someone left off across sessions and providers.
+
 Connect:
   codiedev connect                       Link Claude Code / Codex to your org
 
@@ -34,6 +39,8 @@ Artifacts:
                                          Fetch an artifact (stdout by default)
   codiedev promote <artifact-id>         Promote an auto-extracted artifact
                                          to an authored one
+  codiedev reverse-ticket <pr-url>       Generate a Jira ticket from a merged PR
+                                         (auto-matches spec + thread + transcript)
 
 Messaging:
   codiedev ping <user> "<msg>" [--with <key>]
@@ -45,19 +52,260 @@ Capture:
   codiedev note "<text>"                 Capture a passing thought
 
 Other:
-  codiedev help                          Show this help
+  codiedev help [command]                Show this help, or details for one command
+  codiedev docs                          Print the full usage guide
   codiedev version                       Show version
 
+Filename conventions:
+  spec-*.md      → spec          review-*.md    → review
+  decision-*.md  → decision      proposal-*.md  → proposal
+  bugfix-*.md    → bugfix        anything else  → note
+
+Examples:
+  codiedev push docs/specs/spec-cart-clear.md
+  codiedev pull spec-cart-clear.md
+  codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+  codiedev inbox --unread
+  codiedev note "idempotency key is worth a follow-up"
+
 Backend: ${process.env.CODIEDEV_URL ?? "https://codiedev.com"}
+Token:   https://codiedev.com/portal/integrations/claude-code
+Docs:    codiedev docs
+`.trim();
+const COMMAND_HELP = {
+    connect: `
+codiedev connect — link your agent CLI to CodieDev
+
+  Interactive setup. Prompts for an API token, then installs:
+    - ~/.codiedev/config.json            (token + org + tracked repos)
+    - ~/.claude/settings.json hook       (captures session transcripts)
+    - ~/.claude/CLAUDE.md instructions   (teaches Claude the commands)
+    - ~/.codex/hooks.json hook           (same, for Codex)
+    - ~/.codex/AGENTS.md instructions    (same, for Codex)
+
+  Re-run anytime to swap accounts or refresh the instruction block.
+
+  Get your token: https://codiedev.com/portal/integrations/claude-code
+`.trim(),
+    push: `
+codiedev push — author or update an artifact
+
+  Usage:
+    codiedev push <file.md> [--type spec|review|decision|proposal|bugfix|note]
+
+  The file's basename becomes its key (unique per company). Pushing the
+  same key again creates a new version — full history is preserved.
+
+  Type is inferred from the filename prefix unless you override with --type.
+
+  Examples:
+    codiedev push spec-cart-clear.md
+    codiedev push docs/review-auth.md --type review
+    codiedev push notes/random.md --type note
+`.trim(),
+    pull: `
+codiedev pull — fetch an artifact
+
+  Usage:
+    codiedev pull <key> [--version N] [--out path.md]
+
+  By default prints to stdout (pipe-friendly). --out writes to a file.
+  --version gets a specific historical version; omit for the latest.
+
+  Examples:
+    codiedev pull spec-cart-clear.md
+    codiedev pull spec-cart-clear.md --version 2
+    codiedev pull spec-cart-clear.md --out ./local-copy.md
+    codiedev pull spec-cart-clear.md | less
+`.trim(),
+    ping: `
+codiedev ping — send a teammate a message, optionally attached to an artifact
+
+  Usage:
+    codiedev ping <user> "<message>" [--with <artifact-key>]
+
+  <user> resolves to a teammate in your org by first name, full name,
+  or email. Ambiguous matches return a list — retry with the full email.
+
+  Teammates are notified by email and can reply from their own agent.
+
+  Examples:
+    codiedev ping maya "thoughts on batch vs parallel?" --with spec-cart-clear.md
+    codiedev ping nic@signalandcode.co "can you take this one?"
+`.trim(),
+    inbox: `
+codiedev inbox — show messages from teammates
+
+  Usage:
+    codiedev inbox [--unread] [--limit N]
+
+  Lists pings with sender, subject artifact, and preview. Each row
+  shows a ping-id you can pass to 'codiedev read'.
+
+  Unread rows show as ● ; read rows as · .
+
+  Examples:
+    codiedev inbox
+    codiedev inbox --unread
+    codiedev inbox --limit 10
+`.trim(),
+    read: `
+codiedev read — mark a ping as read and show its full content
+
+  Usage:
+    codiedev read <ping-id>
+
+  Grab the ping-id from 'codiedev inbox'. After reading, the ping will
+  drop out of 'codiedev inbox --unread' and the portal inbox badge
+  decrements for you.
+`.trim(),
+    note: `
+codiedev note — capture a passing thought, linked to your session
+
+  Usage:
+    codiedev note "<text>"
+
+  Stores the note in your org memory so you can search it later or
+  reference it in a ticket. Notes appear in the portal under the
+  Agent Inbox → My authored artifacts.
+
+  Examples:
+    codiedev note "idempotency key is worth a follow-up"
+    codiedev note "timeout threshold feels arbitrary — validate on slow networks"
+`.trim(),
+    promote: `
+codiedev promote — promote an auto-extracted artifact to authored
+
+  Usage:
+    codiedev promote <artifact-id> [--key filename.md]
+
+  The session-capture pipeline auto-extracts spec/bugfix/decision
+  artifacts from each agent session. Promote turns one of those into
+  a first-class authored artifact your team can ping, pull, and
+  update versions of.
+
+  Find artifact-ids in the portal under Knowledge → Memory, or via
+  the portal search.
+`.trim(),
+};
+const DOCS = `
+CodieDev — usage guide
+
+## What this is
+
+CodieDev is a team artifact layer on top of your coding agent (Claude
+Code, Codex, etc.). It persists the *durable* outputs of agent work —
+specs, reviews, decisions, proposals, and captured thoughts — so:
+
+  - Your teammates can pick up where you left off without a handoff call.
+  - Your manager can see what's shipping and why, grounded in real
+    session evidence.
+  - Your future self can search "what did we decide about X?" and get
+    a real answer with citations.
+
+## Core loop
+
+  1. You push an artifact:
+       codiedev push spec-cart-clear.md
+
+  2. Your teammate gets pinged (either directly by you, or because
+     they asked to be kept in the loop on that key):
+       codiedev ping maya "thoughts?" --with spec-cart-clear.md
+
+  3. They check their inbox:
+       codiedev inbox
+
+  4. They pull your artifact, edit it, and push back:
+       codiedev pull spec-cart-clear.md > my-copy.md
+       # ...edit...
+       codiedev push my-copy.md   (saves as v2 of the same key)
+
+  5. You pull the updated version and keep building.
+
+## Versions
+
+Every push of the same filename creates a new version. Latest is the
+default on pull; use --version N to get a historical one. All versions
+are preserved — you can always roll back.
+
+## Lifecycle
+
+Artifacts have a status that auto-advances as PRs reference them:
+
+  draft  →  accepted  →  implementing  →  shipped
+                                       →  archived
+
+Artifacts stay editable at every stage, including after merge —
+lessons-learned and follow-up notes append as new versions.
+
+## Portal
+
+Everything you do in the CLI is visible at:
+
+    https://codiedev.com/portal/inbox
+
+Your CTO (or any non-technical teammate) can follow along without ever
+touching a terminal — they read the artifacts in the portal and get
+email notifications when pinged.
+
+## Agent-native
+
+If you use Claude Code or Codex, the agent already knows the commands —
+'codiedev connect' installs instructions into your user-level config.
+Just say things like:
+
+    "push this spec and ping Nic"
+    "any messages?"
+    "pull Maya's latest spec"
+
+The agent will run the right command via Bash.
+
+## Command reference
+
+Run 'codiedev help <command>' for each, or see the quick list:
+
+    codiedev help
+
+## Getting a token
+
+  1. Log in to https://codiedev.com/portal/integrations/claude-code
+  2. Click "Create token"
+  3. Copy the cdv_... string and paste it into 'codiedev connect'
+
+Tokens are per-user. Rotate any time by revoking + creating a new one.
 `.trim();
 async function main() {
     const [, , command, ...rest] = process.argv;
-    if (!command || command === "help" || command === "--help" || command === "-h") {
+    if (!command || command === "--help" || command === "-h") {
         console.log(HELP);
         return;
     }
+    if (command === "help") {
+        const sub = rest[0];
+        if (sub && COMMAND_HELP[sub]) {
+            console.log(COMMAND_HELP[sub]);
+            return;
+        }
+        if (sub) {
+            console.log(`No help for "${sub}". Valid commands:`);
+            console.log(Object.keys(COMMAND_HELP).join(", "));
+            return;
+        }
+        console.log(HELP);
+        return;
+    }
+    if (command === "docs") {
+        console.log(DOCS);
+        return;
+    }
+    // Support `codiedev <command> --help` too.
+    if (rest.includes("--help") || rest.includes("-h")) {
+        if (COMMAND_HELP[command]) {
+            console.log(COMMAND_HELP[command]);
+            return;
+        }
+    }
     if (command === "version" || command === "--version" || command === "-v") {
-        // Package version is replaced at publish via tsc — for now, print the source-of-truth.
         console.log("codiedev cli");
         return;
     }
@@ -94,6 +342,10 @@ async function main() {
             case "promote":
                 await (0, promote_1.runPromote)(rest);
                 return;
+            case "reverse-ticket":
+            case "reverseTicket":
+                await (0, reverseTicket_1.runReverseTicket)(rest);
+                return;
             default:
                 console.error(`Unknown command: ${command}`);
                 console.error(HELP);

package/dist/commands/reverseTicket.d.ts

@@ -0,0 +1 @@
+export declare function runReverseTicket(args: string[]): Promise<void>;

package/dist/commands/reverseTicket.js

@@ -0,0 +1,150 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runReverseTicket = runReverseTicket;
+const child_process_1 = require("child_process");
+const shared_1 = require("./shared");
+function parsePrUrl(url) {
+    const m = url.match(/github\.com\/([^/]+)\/([^/]+)\/pull\/(\d+)/);
+    if (!m)
+        return null;
+    return { owner: m[1], repo: m[2], number: Number(m[3]) };
+}
+function checkGhCli() {
+    try {
+        (0, child_process_1.execSync)("gh --version", { stdio: ["pipe", "pipe", "pipe"] });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function ghApi(path) {
+    const out = (0, child_process_1.execSync)(`gh api "${path}"`, {
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: 50 * 1024 * 1024,
+    }).toString("utf8");
+    return JSON.parse(out);
+}
+function ghRaw(path) {
+    return (0, child_process_1.execSync)(`gh api -H "Accept: application/vnd.github.v3.diff" "${path}"`, {
+        stdio: ["pipe", "pipe", "pipe"],
+        maxBuffer: 50 * 1024 * 1024,
+    }).toString("utf8");
+}
+function parseArgs(args) {
+    let prUrl;
+    let forcedKey;
+    let noTruncate = false;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if ((a === "--with" || a === "-w") && i + 1 < args.length) {
+            forcedKey = args[++i];
+        }
+        else if (a.startsWith("--with=")) {
+            forcedKey = a.slice("--with=".length);
+        }
+        else if (a === "--full") {
+            noTruncate = true;
+        }
+        else if (!a.startsWith("--") && !prUrl) {
+            prUrl = a;
+        }
+    }
+    if (!prUrl) {
+        console.error("Usage: codiedev reverse-ticket <pr-url> [--with <artifact-key>] [--full]");
+        console.error("");
+        console.error("Example: codiedev reverse-ticket https://github.com/signalandcode/repo/pull/42");
+        process.exit(1);
+    }
+    return { prUrl, forcedKey, noTruncate };
+}
+async function runReverseTicket(args) {
+    const { prUrl, forcedKey, noTruncate } = parseArgs(args);
+    const parsed = parsePrUrl(prUrl);
+    if (!parsed) {
+        console.error("Couldn't parse PR URL. Expected format: https://github.com/<owner>/<repo>/pull/<number>");
+        process.exit(1);
+    }
+    if (!checkGhCli()) {
+        console.error("This command needs the `gh` CLI installed and authenticated.");
+        console.error("  brew install gh  (macOS)");
+        console.error("  gh auth login");
+        process.exit(1);
+    }
+    const config = (0, shared_1.requireConfig)();
+    console.log(`Fetching PR ${parsed.owner}/${parsed.repo}#${parsed.number}…`);
+    let prJson;
+    let filesJson;
+    let diff;
+    try {
+        prJson = ghApi(`/repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}`);
+        filesJson = ghApi(`/repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}/files`);
+        // Diff is nice-to-have; truncate if huge.
+        try {
+            const rawDiff = ghRaw(`/repos/${parsed.owner}/${parsed.repo}/pulls/${parsed.number}`);
+            diff = noTruncate ? rawDiff : rawDiff.slice(0, 12_000);
+        }
+        catch {
+            // Skip diff on failure — the writer works without it.
+        }
+    }
+    catch (err) {
+        console.error(`Failed to fetch PR via gh api: ${err.message}`);
+        process.exit(1);
+    }
+    const bundle = {
+        repo: `${parsed.owner}/${parsed.repo}`,
+        number: parsed.number,
+        title: prJson.title ?? "",
+        body: prJson.body ?? "",
+        author: prJson.user?.login ?? "unknown",
+        authorEmail: prJson.user?.email ?? undefined,
+        mergedAt: prJson.merged_at
+            ? Date.parse(prJson.merged_at)
+            : prJson.closed_at
+                ? Date.parse(prJson.closed_at)
+                : Date.now(),
+        filesChanged: (filesJson ?? []).map((f) => f.filename),
+        diff,
+        htmlUrl: prJson.html_url ?? prUrl,
+    };
+    console.log(`  title: ${bundle.title}`);
+    console.log(`  author: ${bundle.author}`);
+    console.log(`  files: ${bundle.filesChanged.length}`);
+    console.log(`  merged: ${new Date(bundle.mergedAt).toISOString()}`);
+    console.log("");
+    console.log("Generating ticket…");
+    console.log("");
+    try {
+        const res = await (0, shared_1.apiRequest)("POST", "/api/cli/reverseTicket", {
+            config,
+            body: {
+                pr: bundle,
+                forcedArtifactKey: forcedKey,
+            },
+        });
+        if (res.match) {
+            console.log(`✓ Matched artifact: ${res.match.key} (score=${res.match.score.toFixed(2)})`);
+            console.log(`  signals · body=${res.match.signals.bodyMention} · files=${res.match.signals.fileOverlap.toFixed(2)} · transcript=${res.match.signals.transcriptEdit}`);
+        }
+        else if (res.candidates.length > 0) {
+            console.log(`? Ambiguous / low confidence. Candidates:`);
+            for (const c of res.candidates.slice(0, 3)) {
+                console.log(`  - ${c.key} (score=${c.score.toFixed(2)})`);
+            }
+            console.log(`  Re-run with --with <key> to force a specific artifact.`);
+        }
+        else {
+            console.log("· No matched artifact. Ticket generated from PR diff alone.");
+        }
+        console.log(`  prompt tokens (est): ${res.tokensInEstimate}`);
+        console.log("");
+        console.log("─────────── Generated ticket ───────────");
+        console.log("");
+        console.log(res.ticket);
+    }
+    catch (err) {
+        console.error(`Reverse-ticket failed: ${err.message}`);
+        process.exit(1);
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codiedev",
-  "version": "0.3.3",
+  "version": "0.3.5",
   "description": "Connect Claude Code or Codex to CodieDev for org-wide session capture and artifact collaboration",
   "bin": {
     "codiedev": "./dist/cli.js",