notas 0.0.0 → 26.2.1

package/README.md

@@ -0,0 +1,115 @@
+# notas
+
+Multi-provider notes & docs CLI. Notion is the first supported provider.
+
+## Install
+
+```bash
+# Homebrew
+brew install circlesac/tap/notas
+
+# npm
+npx @circlesac/notas
+
+# From source
+bun install
+bun run build
+```
+
+## Usage
+
+```bash
+# Authenticate (opens browser for OAuth)
+notas notion auth login
+
+# Or use an integration token
+notas notion auth login --token ntn_xxx
+
+# List databases
+notas notion db list
+
+# Query a database
+notas notion db query <database-id>
+
+# Search
+notas notion search <query>
+
+# Output as JSON
+notas notion db list --output json
+```
+
+### Commands
+
+```
+notas notion auth      login, logout, status, refresh
+notas notion databases list, get, query, create, update, delete
+notas notion pages     get, create, update, archive, restore
+notas notion blocks    list, get, append, update, delete
+notas notion users     list, get, me
+notas notion search    <query>
+notas notion comments  list, create
+notas notion api       <method> <endpoint> [--body json]
+notas notion version
+```
+
+`db` is an alias for `databases`.
+
+## Development
+
+```bash
+# Run locally
+bun run dev -- notion db list
+
+# Lint (oxlint + eslint + prettier + biome + tsc)
+bun run lint
+
+# Type check
+bun run type-check
+
+# Test
+bun run test
+
+# Build native binary
+bun run build
+
+# Full pre-merge check
+bun run pre-merge
+```
+
+## Project Structure
+
+```
+src/
+  index.ts                  CLI entry point
+  lib/                      Shared utilities (credentials, output, errors)
+  platforms/notion/          Notion provider
+    auth/                   login, logout, status, refresh
+    databases/              CRUD + query
+    pages/                  CRUD + archive/restore
+    blocks/                 CRUD + append
+    users/                  list, get, me
+    search/                 full-text search
+    comments/               list, create
+    api.ts                  raw API passthrough
+    client.ts               Notion client factory
+    properties.ts           property formatting
+  types/                    shared types
+worker/                     Cloudflare Worker (OAuth callback relay at notas.circles.ac)
+npm/                        npm distribution (shim + installer)
+homebrew/                   Homebrew formula template
+```
+
+## Deploy
+
+```bash
+# Deploy OAuth callback worker
+bun run deploy:worker
+```
+
+## Release
+
+Releases are triggered via `workflow_dispatch` in GitHub Actions. The workflow runs tests, bumps the version (CalVer via `@circlesac/oneup`), builds native binaries for 4 platforms, creates a GitHub Release, publishes to npm, and updates the Homebrew formula.
+
+```bash
+gh workflow run release.yml
+```

package/bin/install.js

@@ -0,0 +1,63 @@
+import https from "https";
+import fs from "fs";
+import path from "path";
+import { execSync } from "child_process";
+import { fileURLToPath } from "url";
+import { createRequire } from "module";
+
+const require = createRequire(import.meta.url);
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+const REPO = "circlesac/notas-cli";
+
+const PLATFORMS = {
+	"darwin-x64": { artifact: "notas-darwin-x64", ext: ".tar.gz" },
+	"darwin-arm64": { artifact: "notas-darwin-arm64", ext: ".tar.gz" },
+	"linux-x64": { artifact: "notas-linux-x64", ext: ".tar.gz" },
+	"linux-arm64": { artifact: "notas-linux-arm64", ext: ".tar.gz" },
+};
+
+function download(url) {
+	return new Promise((resolve, reject) => {
+		https.get(url, (res) => {
+			if (res.statusCode === 302 || res.statusCode === 301) {
+				return download(res.headers.location).then(resolve).catch(reject);
+			}
+			if (res.statusCode !== 200) return reject(new Error(`HTTP ${res.statusCode}`));
+			const chunks = [];
+			res.on("data", (c) => chunks.push(c));
+			res.on("end", () => resolve(Buffer.concat(chunks)));
+			res.on("error", reject);
+		});
+	});
+}
+
+const nativeDir = path.join(__dirname, "native");
+const binPath = path.join(nativeDir, "notas");
+
+if (!fs.existsSync(binPath)) {
+	const { version } = require("../package.json");
+	if (version) {
+		const platform = `${process.platform}-${process.arch}`;
+		const info = PLATFORMS[platform];
+		if (!info) {
+			console.error(`Unsupported platform: ${platform}`);
+			process.exit(1);
+		}
+
+		const { artifact, ext } = info;
+		const url = `https://github.com/${REPO}/releases/download/v${version}/${artifact}${ext}`;
+		console.info(`Downloading notas v${version} for ${platform}...`);
+
+		const data = await download(url);
+		fs.mkdirSync(nativeDir, { recursive: true });
+
+		const tmp = path.join(nativeDir, `tmp${ext}`);
+		fs.writeFileSync(tmp, data);
+		execSync(`tar xzf "${tmp}"`, { cwd: nativeDir });
+		fs.unlinkSync(tmp);
+
+		fs.chmodSync(binPath, 0o755);
+		console.info("Installed successfully.");
+	}
+}

package/bin/install.sh

@@ -0,0 +1,24 @@
+#!/bin/sh
+set -e
+
+REPO="circlesac/notas-cli"
+INSTALL_DIR="${INSTALL_DIR:-/usr/local/bin}"
+
+OS=$(uname -s | tr '[:upper:]' '[:lower:]')
+ARCH=$(uname -m)
+
+case "$OS-$ARCH" in
+	darwin-arm64)  NAME="notas-darwin-arm64" ;;
+	darwin-x86_64) NAME="notas-darwin-x64" ;;
+	linux-aarch64) NAME="notas-linux-arm64" ;;
+	linux-x86_64)  NAME="notas-linux-x64" ;;
+	*) echo "Unsupported platform: $OS-$ARCH"; exit 1 ;;
+esac
+
+VERSION=$(curl -fsSL "https://api.github.com/repos/$REPO/releases/latest" | grep '"tag_name"' | cut -d'"' -f4)
+URL="https://github.com/$REPO/releases/download/$VERSION/${NAME}.tar.gz"
+
+echo "Installing notas $VERSION..."
+curl -fsSL "$URL" | tar xz -C "$INSTALL_DIR"
+chmod +x "$INSTALL_DIR/notas"
+echo "Installed to $INSTALL_DIR/notas"

package/bin/notas

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+
+import { spawnSync } from "child_process";
+import { existsSync } from "fs";
+import { fileURLToPath } from "url";
+import path from "path";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const bin = path.join(__dirname, "native", "notas");
+
+if (!existsSync(bin)) {
+	await import("./install.js");
+}
+const result = spawnSync(bin, process.argv.slice(2), { stdio: "inherit" });
+process.exit(result.status ?? 1);

package/package.json

@@ -1,7 +1,46 @@
 {
+  "bin": {
+    "notas": "bin/notas"
+  },
+  "dependencies": {
+    "@notionhq/client": "^5.9.0",
+    "citty": "^0.2.1"
+  },
+  "description": "Multi-provider notes & docs CLI",
+  "devDependencies": {
+    "@types/bun": "latest",
+    "@vitest/coverage-v8": "^4.0.18",
+    "vitest": "^4.0.18"
+  },
+  "files": [
+    "bin",
+    "skills"
+  ],
+  "license": "MIT",
+  "module": "src/index.ts",
   "name": "notas",
-  "version": "0.0.0",
-  "description": "Reserved",
-  "main": "index.js",
-  "license": "MIT"
+  "peerDependencies": {
+    "typescript": "^5"
+  },
+  "pi": {
+    "skills": [
+      "./skills"
+    ]
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/circlesac/notas-cli"
+  },
+  "scripts": {
+    "build": "bun build --compile --outfile=dist/notas src/index.ts",
+    "deploy:worker": "cd worker && npx wrangler deploy",
+    "dev": "bun run src/index.ts",
+    "lint": "npx @circlesac/lint --all",
+    "postinstall": "node bin/install.js",
+    "pre-merge": "bun run lint && bun run type-check && bun run test && bun run build",
+    "test": "vitest run",
+    "type-check": "npx tsc --noEmit"
+  },
+  "type": "module",
+  "version": "26.2.1"
 }

package/skills/notion/SKILL.md

@@ -0,0 +1,157 @@
+---
+name: notion
+description: Reference guide for the notas CLI Notion provider. Use this when working with Notion pages, databases, blocks, users, comments, or search.
+---
+
+# notas CLI Reference
+
+## Quick Start
+
+```bash
+notas notion auth login          # OAuth login (opens browser)
+notas notion search "meeting"    # Search across workspace
+notas notion db list             # List all databases
+```
+
+## Global Flags
+
+| Flag | Alias | Description |
+|------|-------|-------------|
+| `--workspace` | `-w` | Select workspace (when multiple configured) |
+| `--json` | | Output as JSON |
+| `--plain` | | Output as tab-separated plain text |
+
+## Authentication
+
+```bash
+notas notion auth login                        # OAuth flow (default)
+notas notion auth login --token ntn_xxx        # Manual token
+notas notion auth login --name work            # Name the workspace
+notas notion auth status                       # Show all workspaces
+notas notion auth logout --name work           # Remove a workspace
+notas notion auth refresh                      # Refresh OAuth token
+notas notion auth rename old-name new-name     # Rename workspace
+```
+
+Environment variable: `NOTION_TOKEN` overrides stored credentials.
+
+## Databases
+
+```bash
+notas notion db list
+notas notion db get <database-id>
+notas notion db query <database-id>
+notas notion db query <database-id> --filter '{"property":"Status","select":{"equals":"Done"}}'
+notas notion db query <database-id> --sort '[{"property":"Created","direction":"descending"}]'
+notas notion db query <database-id> --columns "Name,Status,Date"
+notas notion db create <parent-page-id> --title "My Database"
+notas notion db update <database-id> --title "New Title" --description "Updated"
+notas notion db delete <database-id>
+```
+
+Pagination: `--limit 10`, `--all`, `--cursor <cursor>`
+
+## Pages
+
+```bash
+notas notion pages get <page-id>
+notas notion pages create <parent-id> --title "New Page"
+notas notion pages create <parent-id> --title "Page" --content "Body text"
+notas notion pages create <parent-id> --title "Page" --icon "📝"
+notas notion pages create <db-id> --parent-type database --title "Row" --properties '{"Status":{"select":{"name":"Draft"}}}'
+notas notion pages update <page-id> --title "Updated Title"
+notas notion pages archive <page-id>
+notas notion pages restore <page-id>
+```
+
+Stdin support:
+```bash
+cat notes.md | notas notion pages create <parent-id> --title "From File" --stdio
+```
+
+## Blocks
+
+```bash
+notas notion blocks list <page-id>
+notas notion blocks list <page-id> --recursive    # All nested blocks
+notas notion blocks get <block-id>
+notas notion blocks append <page-id> --text "Hello world"
+notas notion blocks append <page-id> --type heading_1 --text "Title"
+notas notion blocks append <page-id> --type code --text "console.log('hi')" --language javascript
+notas notion blocks append <page-id> --type to_do --text "Task" --checked
+notas notion blocks append <page-id> --type bookmark --url "https://example.com"
+notas notion blocks append <page-id> --type divider
+notas notion blocks append <page-id> --blocks '[{"object":"block","type":"paragraph","paragraph":{"rich_text":[{"type":"text","text":{"content":"Complex block"}}]}}]'
+notas notion blocks update <block-id> --text "Updated text"
+notas notion blocks update <block-id> --body '{"paragraph":{"rich_text":[{"type":"text","text":{"content":"Raw update"}}]}}'
+notas notion blocks delete <block-id>
+```
+
+Block types: `paragraph`, `heading_1`, `heading_2`, `heading_3`, `bulleted_list_item`, `numbered_list_item`, `to_do`, `toggle`, `code`, `quote`, `callout`, `divider`, `bookmark`
+
+Stdin support:
+```bash
+cat code.py | notas notion blocks append <page-id> --type code --language python --stdio
+```
+
+## Search
+
+```bash
+notas notion search "query"
+notas notion search "query" --type page
+notas notion search "query" --type database
+notas notion search --sort ascending
+notas notion search                              # List all (no query)
+```
+
+## Users
+
+```bash
+notas notion users list
+notas notion users list --filter "john"
+notas notion users get <user-id>
+notas notion users me
+```
+
+## Comments
+
+```bash
+notas notion comments list <page-id>
+notas notion comments create --page-id <page-id> --text "New comment"
+notas notion comments create --discussion-id <id> --text "Reply"
+echo "Comment from pipe" | notas notion comments create --page-id <id> --stdio
+```
+
+## Raw API
+
+```bash
+notas notion api GET /v1/users
+notas notion api POST /v1/search --body '{"query":"test"}'
+notas notion api POST /v1/databases/<id>/query '{"page_size":5}'
+notas notion api PATCH /v1/pages/<id> --body '{"archived":true}'
+```
+
+## Common Workflows
+
+### Create a page with content from a file
+```bash
+cat document.md | notas notion pages create <parent-id> --title "My Doc" --stdio
+```
+
+### Query a database and pipe to jq
+```bash
+notas notion db query <db-id> --json | jq '.results[].properties.Name.title[0].plain_text'
+```
+
+### Append multiple blocks from a script
+```bash
+notas notion blocks append <page-id> --type heading_1 --text "Section Title"
+notas notion blocks append <page-id> --text "Paragraph content"
+cat snippet.py | notas notion blocks append <page-id> --type code --language python --stdio
+```
+
+### Search and get page content
+```bash
+PAGE_ID=$(notas notion search "meeting notes" --json | jq -r '.results[0].id')
+notas notion blocks list $PAGE_ID --recursive --plain
+```

package/index.js

@@ -1 +0,0 @@
-