@octonote/cli 0.0.0-stage → 0.1.3

package/dist/core/login.js

@@ -0,0 +1,119 @@
+/**
+ * `octonote login`: open the browser on <web>/cli/connect, where you click
+ * Authorize; the page hands the new token to this process over a one-shot
+ * server on 127.0.0.1. The server only accepts a POST from the Octonote
+ * site carrying the random `state` we generated, then shuts down. If the
+ * browser can't reach it, the page shows the token to paste here instead.
+ */
+import { spawn } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { createServer, } from "node:http";
+import { hostname } from "node:os";
+import { createInterface } from "node:readline";
+import { CliError } from "./errors.js";
+export const TOKEN_RE = /^ont_[A-Za-z0-9_-]{20,}$/;
+export function openBrowser(url) {
+    const [cmd, args] = process.platform === "darwin"
+        ? ["open", [url]]
+        : process.platform === "win32"
+            ? ["cmd", ["/c", "start", "", url]]
+            : ["xdg-open", [url]];
+    try {
+        const child = spawn(cmd, args, {
+            stdio: "ignore",
+            detached: true,
+        });
+        child.on("error", () => undefined);
+        child.unref();
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export async function browserLogin(opts) {
+    const state = randomBytes(24).toString("base64url");
+    const origin = new URL(opts.webUrl).origin;
+    let settle;
+    let fail;
+    const result = new Promise((res, rej) => {
+        settle = res;
+        fail = rej;
+    });
+    const server = createServer((req, res) => handle(req, res));
+    const cors = (res) => {
+        res.setHeader("access-control-allow-origin", origin);
+        res.setHeader("access-control-allow-methods", "POST, OPTIONS");
+        res.setHeader("access-control-allow-headers", "content-type");
+        // Chrome's Private Network Access: a public site may call localhost only if we say so.
+        res.setHeader("access-control-allow-private-network", "true");
+        res.setHeader("cache-control", "no-store");
+    };
+    function handle(req, res) {
+        cors(res);
+        const url = new URL(req.url ?? "/", "http://127.0.0.1");
+        if (url.pathname !== "/cb")
+            return void res.writeHead(404).end();
+        if (req.method === "OPTIONS")
+            return void res.writeHead(204).end();
+        if (req.method !== "POST" ||
+            (req.headers.origin && req.headers.origin !== origin)) {
+            return void res.writeHead(403).end();
+        }
+        let body = "";
+        req.on("data", (c) => {
+            body += c;
+            if (body.length > 10_000)
+                req.destroy();
+        });
+        req.on("end", () => {
+            let data = {};
+            try {
+                data = JSON.parse(body);
+            }
+            catch {
+                // Fall through to the checks below.
+            }
+            if (data.state !== state || !data.token || !TOKEN_RE.test(data.token)) {
+                return void res.writeHead(400).end();
+            }
+            res
+                .writeHead(200, { "content-type": "application/json" })
+                .end('{"ok":true}');
+            settle({ token: data.token, email: data.email || null });
+        });
+    }
+    await new Promise((res, rej) => {
+        server.once("error", rej);
+        server.listen(0, "127.0.0.1", () => res());
+    });
+    const port = server.address().port;
+    const url = `${opts.webUrl}/cli/connect?${new URLSearchParams({
+        cb: `http://127.0.0.1:${port}/cb`,
+        state,
+        name: hostname().split(".")[0] ?? "",
+    }).toString()}`;
+    opts.onUrl(url);
+    openBrowser(url);
+    // Paste fallback: a person can paste the token the page shows.
+    let rl = null;
+    if (process.stdin.isTTY) {
+        rl = createInterface({ input: process.stdin });
+        rl.on("line", (line) => {
+            const token = line.trim();
+            if (TOKEN_RE.test(token))
+                settle({ token, email: null });
+        });
+    }
+    const timer = setTimeout(() => fail(new CliError("Timed out waiting for the browser.", "LOGIN_TIMEOUT", {
+        hint: "Run `octonote login` again.",
+    })), opts.timeoutMs ?? 5 * 60_000);
+    try {
+        return await result;
+    }
+    finally {
+        clearTimeout(timer);
+        rl?.close();
+        server.close();
+    }
+}

package/dist/core/output.js

@@ -0,0 +1,62 @@
+/**
+ * Output rules (what agents rely on):
+ *  - stdout carries only the result; progress and hints go to stderr.
+ *  - JSON when stdout isn't a terminal (or with --json); readable text for
+ *    people in a terminal (or with --pretty).
+ *  - Errors: JSON `{ "error": { code, message, hint } }` on stdout when in
+ *    JSON mode, else a readable line on stderr; non-zero exit code always.
+ */
+import { CliError } from "./errors.js";
+let mode = process.stdout.isTTY ? "pretty" : "json";
+let quiet = false;
+export function setOutputMode(next) {
+    if (next.json)
+        mode = "json";
+    else if (next.pretty)
+        mode = "pretty";
+    quiet = Boolean(next.quiet);
+}
+export const outputMode = () => mode;
+/** Print a result: JSON as-is, or `pretty(data)` for people. */
+export function emit(data, pretty) {
+    if (mode === "json") {
+        process.stdout.write(`${JSON.stringify(data, null, 2)}\n`);
+        return;
+    }
+    const text = pretty ? pretty(data) : JSON.stringify(data, null, 2);
+    if (text)
+        process.stdout.write(text.endsWith("\n") ? text : `${text}\n`);
+}
+/** Progress / notes for people, on stderr so stdout stays clean. */
+export function info(message) {
+    if (!quiet && mode === "pretty")
+        process.stderr.write(`${message}\n`);
+}
+export function reportError(err) {
+    const e = err instanceof CliError
+        ? err
+        : new CliError(err instanceof Error ? err.message : String(err), "INTERNAL");
+    if (mode === "json") {
+        process.stdout.write(`${JSON.stringify(e.toJSON(), null, 2)}\n`);
+    }
+    else {
+        process.stderr.write(`✗ ${e.message}${e.code !== "INTERNAL" ? ` (${e.code})` : ""}\n`);
+        if (e.hint)
+            process.stderr.write(`  ${e.hint}\n`);
+    }
+    return e.exitCode;
+}
+/** A plain text table for people. */
+export function table(rows, columns) {
+    if (rows.length === 0)
+        return "(none)";
+    const widths = columns.map((c) => Math.max(c.length, ...rows.map((r) => (r[c] ?? "").length)));
+    const line = (cells) => cells
+        .map((cell, i) => cell.padEnd(widths[i]))
+        .join("  ")
+        .trimEnd();
+    return [
+        line(columns.map((c) => c.toUpperCase())),
+        ...rows.map((r) => line(columns.map((c) => r[c] ?? ""))),
+    ].join("\n");
+}

package/dist/core/refs.js

@@ -0,0 +1,41 @@
+/**
+ * Octonote ids carry their kind (pag_ note, cnv_ canvas, prj_ project,
+ * ntb_ notebook), so most commands accept any id and know what it is.
+ */
+import { usage } from "./errors.js";
+export const KIND_BY_PREFIX = {
+    pag: "page",
+    cnv: "canvas",
+    prj: "project",
+    ntb: "notebook",
+};
+/** What people call each kind. */
+export const KIND_NAME = {
+    page: "note",
+    canvas: "canvas",
+    project: "project",
+    notebook: "notebook",
+};
+const APP_PATH = {
+    page: "n",
+    canvas: "c",
+    project: "p",
+    notebook: "nb",
+};
+const ID_RE = /^(pag|cnv|prj|ntb)_[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/;
+/** Accepts a bare id or an app / share URL that contains one. */
+export function parseRef(input, expect) {
+    const match = input.match(/(pag|cnv|prj|ntb)_[0-9a-f-]{36}/);
+    const id = match?.[0];
+    if (!id || !ID_RE.test(id)) {
+        throw usage(`"${input}" isn't an Octonote id.`, "Ids look like pag_… (note), cnv_… (canvas), prj_… (project) or ntb_… (notebook). `octonote list` shows them.");
+    }
+    const kind = KIND_BY_PREFIX[id.slice(0, 3)];
+    if (expect && kind !== expect) {
+        throw usage(`${id} is a ${KIND_NAME[kind]}, not a ${KIND_NAME[expect]}.`);
+    }
+    return { kind, id };
+}
+export function appUrl(webUrl, kind, id) {
+    return `${webUrl}/${APP_PATH[kind]}/${id}`;
+}

package/dist/core/resources.js

@@ -0,0 +1,23 @@
+import { appUrl, KIND_NAME } from "./refs.js";
+export function item(ctx, kind, row) {
+    return {
+        kind: KIND_NAME[kind],
+        id: row.id,
+        title: row.title ?? row.name ?? "",
+        url: appUrl(ctx.config.webUrl, kind, row.id),
+        ...(row.notebookId !== undefined ? { notebookId: row.notebookId } : {}),
+        ...(row.updatedAt ? { updatedAt: row.updatedAt } : {}),
+    };
+}
+export async function setPublished(ctx, kind, id, published) {
+    return ctx.api.put(`/${kind}/${id}/publish`, { published });
+}
+export function describeItem(i) {
+    return [
+        `${i.kind} ${i.title ? `“${i.title}” ` : ""}${i.id}`,
+        `  ${i.url}`,
+        i.publicUrl ? `  public: ${i.publicUrl}` : "",
+    ]
+        .filter(Boolean)
+        .join("\n");
+}

package/dist/core/run.js

@@ -0,0 +1,19 @@
+import { createContext } from "./context.js";
+import { reportError, setOutputMode } from "./output.js";
+export function action(handler, opts = {}) {
+    return async (...args) => {
+        // Commander passes (...positional, options, command).
+        const command = args[args.length - 1];
+        const globals = command.optsWithGlobals();
+        setOutputMode(globals);
+        try {
+            const ctx = await createContext(globals, {
+                requireAuth: opts.auth !== false,
+            });
+            await handler(ctx, ...args.slice(0, -1));
+        }
+        catch (err) {
+            process.exitCode = reportError(err);
+        }
+    };
+}

package/dist/guide/agent-guide.js

@@ -0,0 +1,90 @@
+/**
+ * The guide agents read — one source for `octonote guide`, the section
+ * `octonote setup` writes into CLAUDE.md / AGENTS.md, and the Claude Code
+ * skill. Keep it short and task-first: agents act on the first screen.
+ */
+/** Short pointer for CLAUDE.md / AGENTS.md (the full guide is one command away). */
+export const PROJECT_SECTION = `## Octonote (notes & canvases)
+
+The user keeps notes, diagrams (canvases), projects and notebooks in Octonote. Use the \`octonote\` CLI to read and write them — never ask the user to copy-paste.
+
+- Run \`octonote guide\` once per session before using it; \`octonote <command> --help\` for details.
+- Write notes as markdown files (mermaid, \`$math$\`, code and tables work); draw diagrams as mermaid flowcharts (\`--from-mermaid\`), which become real, editable canvases.
+- Output is JSON when piped: read \`id\`, \`url\` and \`publicUrl\` from it, and always give the user the link.
+- Only publish, share or delete when the user asked to.
+`;
+export const AGENT_GUIDE = `# Octonote CLI — guide for agents
+
+Octonote holds the user's **notes** (markdown documents), **canvases** (diagrams),
+**projects** (one note + one canvas, side by side) and **notebooks** (folders).
+The \`octonote\` CLI is how you read and write them on the user's behalf.
+
+## Rules
+- Output is JSON when piped (force with --json). Errors print
+  \`{"error":{"code","message","hint"}}\` and exit non-zero; branch on \`code\`.
+- Never prompts. Content comes from --file <path>, --stdin, or "-" as the path.
+- Every result has \`id\`, \`url\` (app link) and, once published, \`publicUrl\`.
+  Give the user the link at the end.
+- Ids carry their kind: pag_ note, cnv_ canvas, prj_ project, ntb_ notebook.
+  Notebooks can also be named by exact name (--notebook "Architecture").
+- Publish, share, invite or delete only when the user asked for it.
+  \`delete\` requires --yes.
+- Not signed in (code NOT_LOGGED_IN)? Ask the user to run \`octonote login\`
+  (or set OCTONOTE_TOKEN). Don't try to sign in yourself.
+
+## Write a note
+  octonote note create "Title" --file doc.md [--notebook "Name"] [--publish]
+  cat doc.md | octonote note create "Title" --stdin
+Markdown → rich note: headings, lists, checklists, tables, code, quotes,
+images (by URL), \`$inline math$\`, \`$$display math$$\`, and \`\`\`mermaid blocks
+(rendered diagrams inside the note).
+
+## Read and edit a note
+  octonote note show <id>                 # markdown to stdout
+  octonote note pull <id> -o note.md      # file with front matter (keeps the id)
+  # …edit note.md…
+  octonote note push note.md              # replaces the note's content
+  octonote note append <id> --text "- new item"   # or --file / --stdin
+  octonote note rename <id> "New title"
+
+## Draw a canvas (diagram)
+Write a mermaid **flowchart** and let Octonote lay it out as real shapes:
+  octonote canvas create "Login flow" --from-mermaid flow.mmd [--publish]
+  octonote canvas redraw <id> --from-mermaid flow.mmd
+Supported: \`graph|flowchart TD|LR|BT|RL\`; nodes A[box] A(round) A([stadium])
+A((circle)) A{decision} A[(database)] A{{hexagon}}; edges --> --- -.-> ==> <-->
+with labels (A -->|yes| B or A -- yes --> B); chains; A & B --> C;
+\`subgraph id [Title] … end\`. Other diagram types (sequence, gantt…) can't be
+canvases — put them in a note as a \`\`\`mermaid block instead.
+Raw tldraw JSON also works: \`canvas pull <id> -o c.json\` / \`canvas push c.json --id <id>\`.
+
+## Project = note + canvas
+  octonote project create "Auth flow" --note auth.md --canvas-mermaid auth.mmd \\
+    [--view split|notes|canvas] [--notebook "Name"] [--publish]
+  octonote project show <id>     # ids of its note and canvas (edit them as above)
+
+## Organise
+  octonote list [--kind note|canvas|project|notebook] [--notebook "Name"]
+  octonote search <words>                 # by title
+  octonote notebook list | create "Name" | show "Name"
+  octonote move <id> --notebook "Name"    # or --out
+  octonote delete <id> --yes
+
+## Publish and share
+  octonote publish <id>        # → publicUrl (a public, read-only page)
+  octonote unpublish <id>
+  octonote share <id> --email person@example.com --role viewer|editor
+  octonote share <id> --link view|edit|off   # anyone with the app link
+Publishing a notebook publishes everything inside it.
+
+## Account
+  octonote whoami | workspace list | workspace use <name|id> | logout
+  octonote account rename "Full Name"     # display name (author on published pages)
+`;
+/** Claude Code skill file (.claude/skills/octonote/SKILL.md). */
+export const CLAUDE_SKILL = `---
+name: octonote
+description: Read and write the user's Octonote notes, canvases (diagrams), projects and notebooks with the octonote CLI — create notes from markdown, draw diagrams from mermaid flowcharts, publish and share them. Use when the user mentions Octonote, their notes or notebooks, or asks to document, diagram, write up or publish something there.
+---
+
+${AGENT_GUIDE}`;

package/dist/guide/getting-started.js

@@ -0,0 +1,44 @@
+/**
+ * What `octonote` prints with no command — right after install, too, since
+ * the install line is `npm i -g … && octonote`. (npm hides messages printed
+ * during install, so this is where setup help lives.) Everything needed to
+ * get going, without opening the docs.
+ */
+export const DOCS_URL = "https://octonote.ai/cli";
+export function gettingStarted(opts) {
+    const signIn = opts.signedInAs
+        ? `  ✓ Signed in as ${opts.signedInAs}`
+        : `  1. Sign in            octonote login
+                        (no browser? set OCTONOTE_TOKEN from Settings → CLI & agents)`;
+    return `
+  octonote ${opts.version} — Octonote from your terminal, Claude Code and Codex
+
+GET STARTED
+${signIn}
+  ${opts.signedInAs ? "1." : "2."} Teach your agent   octonote setup claude      # this project's CLAUDE.md
+                        octonote setup claude --global --skill   # every project + skill
+                        octonote setup codex       # this project's AGENTS.md
+                        octonote setup codex --global
+     Then just ask: “write this up in Octonote”, “draw this as an Octonote canvas”.
+
+  Claude Code: allow it without prompts — add to ~/.claude/settings.json:
+    { "permissions": { "allow": ["Bash(octonote:*)"] } }
+  Codex: its sandbox blocks the network by default — in ~/.codex/config.toml:
+    [sandbox_workspace_write]
+    network_access = true
+
+COMMON COMMANDS
+  octonote note create "Title" --file doc.md      note from markdown
+  octonote note pull <id> -o doc.md               edit locally, then: note push doc.md
+  octonote canvas create "Flow" --from-mermaid flow.mmd   draw a diagram
+  octonote project create "Name" --note doc.md --canvas-mermaid flow.mmd
+  octonote list · search <words> · notebook list
+  octonote publish <id> · share <id> --email … --role viewer|editor
+
+HELP
+  octonote --help              all commands
+  octonote <command> --help    one command, e.g. octonote note create --help
+  octonote guide               the full guide written for AI agents
+  ${DOCS_URL}     docs on the web
+`;
+}

package/dist/index.js

@@ -0,0 +1,73 @@
+#!/usr/bin/env node
+/**
+ * octonote — the Octonote command-line tool, built for people and for
+ * agents (Claude Code, Codex). Commands live in ./commands; shared
+ * plumbing (config, HTTP, output, errors) in ./core; the agent guide in
+ * ./guide. The CLI only talks to the public Octonote API.
+ */
+import { realpathSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { Command } from "commander";
+import { registerAgents } from "./commands/agents.js";
+import { registerAuth } from "./commands/auth.js";
+import { registerCanvas } from "./commands/canvas.js";
+import { registerItems } from "./commands/items.js";
+import { registerNote } from "./commands/note.js";
+import { registerNotebook } from "./commands/notebook.js";
+import { registerProject } from "./commands/project.js";
+import { resolveConfig } from "./core/config.js";
+import { DOCS_URL, gettingStarted } from "./guide/getting-started.js";
+import { VERSION } from "./version.js";
+export { VERSION } from "./version.js";
+export function buildProgram() {
+    const program = new Command()
+        .name("octonote")
+        .description("Octonote from your terminal — and from Claude Code or Codex.\nAgents: run `octonote guide` first.")
+        .version(VERSION)
+        .option("--json", "JSON output (default when piped)")
+        .option("--pretty", "human output (default in a terminal)")
+        .option("-q, --quiet", "no progress messages")
+        .option("-w, --workspace <id>", "workspace to use (default: yours)")
+        .option("--api-url <url>", "Octonote API (default: OCTONOTE_API_URL or the hosted API)")
+        .option("--web-url <url>", "Octonote web app (default: OCTONOTE_WEB_URL or https://octonote.ai)")
+        .showHelpAfterError("(run with --help for usage)")
+        .configureOutput({
+        // Usage errors: say what's wrong without dumping the full help.
+        outputError: (str, write) => write(str),
+    });
+    // `octonote` on its own: the getting-started screen (also shown right
+    // after install — the install line ends in `&& octonote`).
+    program.action(async () => {
+        const { token, tokenSource, email } = await resolveConfig();
+        const signedInAs = token
+            ? (email ?? (tokenSource === "env" ? "OCTONOTE_TOKEN" : "your account"))
+            : null;
+        process.stdout.write(gettingStarted({ version: VERSION, signedInAs }));
+    });
+    registerAuth(program);
+    registerNote(program);
+    registerCanvas(program);
+    registerProject(program);
+    registerNotebook(program);
+    registerItems(program);
+    registerAgents(program);
+    program.addHelpText("after", `\nGetting started (sign-in, Claude Code & Codex setup): run \`octonote\` on its own.\nAgents: \`octonote guide\`. Docs: ${DOCS_URL}`);
+    return program;
+}
+// Run only when executed (npm's bin link resolves to this file), not when imported by tests.
+function isMain() {
+    try {
+        return (realpathSync(process.argv[1] ?? "") === fileURLToPath(import.meta.url));
+    }
+    catch {
+        return false;
+    }
+}
+if (isMain()) {
+    buildProgram()
+        .parseAsync(process.argv)
+        .catch((err) => {
+        process.stderr.write(`${err instanceof Error ? err.message : String(err)}\n`);
+        process.exitCode = 1;
+    });
+}

package/dist/reference.js

@@ -0,0 +1,48 @@
+import { AGENT_GUIDE, PROJECT_SECTION } from "./guide/agent-guide.js";
+function options(cmd) {
+    return cmd.options
+        .filter((o) => !["--help", "--version"].includes(o.long ?? ""))
+        .map((o) => ({
+        flags: o.flags,
+        description: o.description,
+        required: o.mandatory,
+        ...(o.defaultValue !== undefined
+            ? { default: String(o.defaultValue) }
+            : {}),
+    }));
+}
+export function buildReference(program, version) {
+    const commands = [];
+    const walk = (cmd, prefix) => {
+        for (const sub of cmd.commands) {
+            const path = [...prefix, sub.name()];
+            if (sub.commands.length) {
+                walk(sub, path);
+                continue;
+            }
+            commands.push({
+                name: path.join(" "),
+                aliases: sub.aliases(),
+                description: sub.description(),
+                arguments: sub.registeredArguments.map((a) => ({
+                    name: a.name(),
+                    description: a.description,
+                    required: a.required,
+                    variadic: a.variadic,
+                    ...(a.defaultValue !== undefined
+                        ? { default: String(a.defaultValue) }
+                        : {}),
+                })),
+                options: options(sub),
+            });
+        }
+    };
+    walk(program, []);
+    return {
+        version,
+        globalOptions: options(program),
+        commands,
+        guide: AGENT_GUIDE,
+        projectSection: PROJECT_SECTION,
+    };
+}

package/dist/version.js

@@ -0,0 +1,2 @@
+/** The CLI's version — keep in step with package.json (a test checks). */
+export const VERSION = "0.1.3";

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@octonote/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.3",
+  "description": "The octonote command-line tool: lets you — and agents like Claude Code and Codex — create, edit, publish and share Octonote notes, canvases, projects and notebooks.",
+  "homepage": "https://octonote.ai/cli",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CoderCouple/octonote-ai.git",
+    "directory": "packages/cli"
+  },
+  "type": "module",
+  "bin": {
+    "octonote": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/gen-reference.mjs",
+    "dev": "tsx src/index.ts",
+    "lint": "echo \"lint pending\"",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "check:reference": "node scripts/gen-reference.mjs --check"
+  },
+  "dependencies": {
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.2",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2",
+    "vitest": "^4.1.9"
+  },
+  "keywords": [
+    "octonote",
+    "cli",
+    "notes",
+    "canvas",
+    "mermaid",
+    "claude",
+    "codex",
+    "ai-agent"
+  ],
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  }
+}