@khanglvm/outline-cli 0.1.1

package/.env.test.example

@@ -0,0 +1,2 @@
+OUTLINE_TEST_BASE_URL=https://example.getoutline.site
+OUTLINE_TEST_API_KEY=ol_api_replace_me

package/AGENTS.md

@@ -0,0 +1,107 @@
+# AGENTS.md
+
+## Scope
+This repository contains `outline-cli` (`outline-agent` alias), a Node.js CLI optimized for AI agents to interact with Outline via real API calls.
+
+## Core Principles
+- Keep outputs deterministic and machine-readable.
+- Optimize for low-token workflows (`summary/ids` views first, hydrate later).
+- Prefer batch operations for fewer round trips.
+- Never mutate existing workspace content in tests except suite-created test documents.
+- Keep security strict: no hardcoded live secrets in tracked files.
+
+## Runtime + Commands
+- Node.js: `>=18.17`
+- Install: `npm install`
+- Basic check: `npm run check`
+- Full tests (real environment): `npm test`
+
+## Repository Map
+- CLI entrypoint: `bin/outline-cli.js`
+- Command wiring/output modes: `src/cli.js`
+- API client/auth/retry: `src/outline-client.js`
+- Tool registry/core tools: `src/tools.js`
+- Navigation/search tools: `src/tools.navigation.js`
+- Mutation/revision tools: `src/tools.mutation.js`
+- Platform/cleanup/capabilities tools: `src/tools.platform.js`
+- Tool arg validation: `src/tool-arg-schemas.js`
+- Live integration tests: `test/live.integration.test.js`
+
+## Local Environment
+- Template: `.env.test.example`
+- Local secret file (untracked): `.env.test.local`
+- Required vars for live tests:
+  - `OUTLINE_TEST_BASE_URL`
+  - `OUTLINE_TEST_API_KEY`
+
+## Development Workflow
+1. Pull latest branch and inspect current tool contracts:
+   - `node ./bin/outline-cli.js tools contract all --result-mode inline`
+2. Refresh raw API method inventory from prior sessions / wrappers, then diff wrapped vs raw:
+   - `rg -o 'client\\.call\\(\"[^\"]+\"' src | sed -E 's/.*\\(\"//; s/\"$//' | sort | uniq`
+   - record missing high-value endpoints in `/tmp/knowledges/outline-raw-api-gap.md`
+3. Implement minimal, compatible changes (preserve response envelopes).
+4. Add/adjust arg schema in `src/tool-arg-schemas.js` for every new tool arg.
+5. Add/adjust real integration tests in `test/live.integration.test.js`.
+6. Run:
+   - `npm run check`
+   - `npm test`
+7. Update docs when behavior/signature changes:
+   - `README.md`
+   - `docs/TOOL_CONTRACTS.md`
+
+## Testing Rules (Live Env)
+- No mocks when endpoint can be exercised live.
+- Mutation tests must:
+  - create a dedicated test doc first,
+  - perform all edits/patch/revision operations on that doc,
+  - delete it in cleanup.
+- Read-only tools (search/list/info) may use site-wide data.
+- Keep tests resilient: isolate steps with subtests and clear assertions.
+
+## Tool/Output Requirements
+- Default JSON output remains stable.
+- `--output ndjson` must stay stream-friendly and compatible with file-offload behavior.
+- Large responses should offload to temp files when `result-mode` is `auto|file`.
+- `batch` should default to token-efficient item payloads; full envelopes opt-in.
+
+## Agent Action Gate
+- Mutating actions are gated by default and must be explicit:
+  - pass `performAction: true` on mutation/delete operations.
+- Safe delete flow requires prior read confirmation:
+  1. Call `documents.info` with `armDelete: true` on target document(s).
+  2. Use returned `deleteReadReceipt.token` as `readToken` for delete.
+  3. Execute delete only with `performAction: true`.
+- Delete operations must fail if read token is missing, stale, mismatched, or expired.
+
+## Security + Secrets
+- Never commit real Outline API keys or `.env.test.local`.
+- Secret scan guard test must pass.
+- If a key is exposed, rotate immediately and update local env.
+
+## Deployment / Release
+- Pre-release checklist:
+  1. Ensure clean git working tree.
+  2. Ensure `OUTLINE_ENTRY_BUILD_KEY` is set (`.env.local` or env).
+  3. Ensure npm auth is ready (`npm login`).
+- Primary workflow command:
+  - `npm run release -- --bump patch`
+  - or `npm run release -- --version X.Y.Z`
+- Prepare-only workflow (no publish/push):
+  - `npm run release:prepare -- --bump patch`
+- Agent execution rule:
+  - If user asks to "deploy" or "release", run `npm run release -- --bump patch` by default unless user specifies a version/tag strategy.
+- Release script responsibilities (`scripts/release.mjs`):
+  - version bump (`npm version --no-git-tag-version`)
+  - changelog update (`CHANGELOG.md`)
+  - integrity refresh (`npm run integrity:refresh`)
+  - verification (`npm run check`, `npm test`)
+  - packaging validation (`npm pack --dry-run`)
+  - git commit + tag (`chore(release): vX.Y.Z`, `vX.Y.Z`)
+  - npm publish (`--access public`) and git push to `origin`
+
+## Temporary Knowledge Notes
+Use local scratch references under:
+- `/tmp/knowledges/*.md`
+
+These are intentionally ignored by git and can store short-lived research/decision notes.

package/CHANGELOG.md

@@ -0,0 +1,102 @@
+# Changelog
+
+## 0.1.1 - 2026-03-05
+
+- Initial tagged release notes.
+- feat(help): add ai skill guidance section for scenario workflows (81a6368)
+- feat(uc19): add compliance oauth tests and docs (b97ab28)
+- feat(uc19): add oauth client and auth wrappers (c1c31f8)
+- feat(uc14): add permanent delete docs and tests (c336bb8)
+- feat(uc14): add permanent delete wrapper (fa99d2e)
+- feat(uc09): add apply_patch_safe tests and docs (41078ae)
+- feat(uc09): add apply_patch_safe wrapper (bc87f7e)
+- feat(uc07): add issue ref helper tests and docs (3254bf5)
+- feat(uc07): add issue reference helper tools (ccf09bc)
+- feat(uc13): add workspace automation tests and docs (75776b4)
+- feat(uc13): add user lifecycle automation wrappers (877adbe)
+- feat(uc12): add migration scenario tests and docs (db33d85)
+- feat(uc12): add import and file operation primitives (25316c5)
+- feat(uc11): add template pipeline tests and docs (c3b126d)
+- feat(uc11): add placeholder pipeline tools (e5fe193)
+- feat(uc10): add graph scenario tests and docs (e2f497a)
+- feat(uc10): add graph traversal helpers (33432d9)
+- feat(uc09): add rollback-safety scenario tests and docs (7bc947c)
+- feat(uc09): add revisions diff helper (d94511e)
+- feat(uc07): add issue-link scenario tests and docs (508281f)
+- feat(uc07): add data-attribute wrappers and schema alignment (cec94ce)
+- feat(uc06): add role-visibility scenario tests and docs (9f2b2ae)
+- feat(uc06): harden role and membership contracts (76d33d7)
+- feat(uc05): add sharing scenario tests and docs (fbc35a2)
+- feat(uc05): harden share lifecycle contracts (6f594f0)
+- feat(uc04): add internal-faq scenario coverage and docs (7cbb697)
+- feat(uc03): add meeting-notes scenario coverage and docs (4f4fb0f)
+- chore: checkpoint local outline-cli changes (9e75cd9)
+- fix(validation): validate expectedRevision in documents.apply_patch (e51fb8b)
+- test(schema): add coverage for federated and terminology tools (b925c48)
+- feat(workflows): add federated and terminology composite tools (5b3fa36)
+- test(schema): cover new scenario wrappers and safety rules (35401fb)
+- feat(tools): add scenario-critical wrappers and safety hardening (d4d9fac)
+- docs(usecases): improve UC-20 issue traceability (111f4fd)
+- docs(usecases): improve UC-19 issue traceability (7dc1278)
+- docs(usecases): improve UC-18 issue traceability (8d594f4)
+- docs(usecases): improve UC-17 issue traceability (2da81d5)
+- docs(usecases): improve UC-16 issue traceability (df28cb2)
+- docs(usecases): improve UC-15 issue traceability (d831dac)
+- docs(usecases): improve UC-14 issue traceability (9947f95)
+- docs(usecases): improve UC-13 issue traceability (ecd07c7)
+- docs(usecases): improve UC-12 issue traceability (7d3dfdc)
+- docs(usecases): improve UC-11 issue traceability (1155797)
+- docs(usecases): improve UC-10 issue traceability (8770670)
+- docs(usecases): improve UC-09 issue traceability (01733dd)
+- docs(usecases): improve UC-08 issue traceability (11b7892)
+- docs(usecases): improve UC-07 issue traceability (66fd433)
+- docs(usecases): improve UC-06 issue traceability (f769da8)
+- docs(usecases): improve UC-05 issue traceability (0dc78b5)
+- docs(usecases): improve UC-04 issue traceability (d8afaf4)
+- docs(usecases): improve UC-03 issue traceability (b8ac03e)
+- docs(usecases): improve UC-02 issue traceability (6305567)
+- docs(usecases): improve UC-01 issue traceability (e3b3459)
+- docs(usecases): add index for UC scenario artifacts (32ce730)
+- docs(usecases): add UC-20 secure lifecycle governance improvement (3a5abe0)
+- docs(usecases): add UC-19 compliance access auditability improvement (39a6843)
+- docs(usecases): add UC-18 terminology refactor improvement (64e4df1)
+- docs(usecases): add UC-17 editorial review lifecycle improvement (692cefa)
+- docs(usecases): add UC-16 federated search sync improvement (b3bad9a)
+- docs(usecases): add UC-15 ai semantic qa improvement (6cd384e)
+- docs(usecases): add UC-14 webhook workflow improvement (9cadbea)
+- docs(usecases): add UC-13 api driven workspace automation improvement (c80a6a9)
+- docs(usecases): add UC-12 legacy wiki migration improvement (6c00a56)
+- docs(usecases): add UC-11 template driven doc pipeline improvement (39a492b)
+- docs(usecases): add UC-10 crosslinked knowledge graph improvement (4a90748)
+- docs(usecases): add UC-09 postmortem rca rollback safety improvement (d6a02dd)
+- docs(usecases): add UC-08 runbooks incident playbooks improvement (48df335)
+- docs(usecases): add UC-07 project docs issue linkage improvement (c7804bb)
+- docs(usecases): add UC-06 role based department spaces improvement (f3f14fe)
+- docs(usecases): add UC-05 public docs sharing improvement (5f56b43)
+- docs(usecases): add UC-04 internal faq knowledge base improvement (1d3c1c9)
+- docs(usecases): add UC-03 meeting notes decision logs improvement (9a115d3)
+- docs(usecases): add UC-02 sop policy wiki improvement (f34462e)
+- docs(usecases): add UC-01 handbook onboarding improvement (1d41ab0)
+- wip (5dae3ea)
+
+All notable changes to this project are documented in this file.
+
+The format follows Keep a Changelog principles and this project uses Semantic Versioning.
+
+## Unreleased
+
+### Changed
+
+- Improved top-level documentation with a user-focused quickstart and clearer operational guidance.
+
+### Added
+
+- Added a compact AI-agent instruction section in `README.md` for deterministic low-token workflows.
+
+## 0.1.0 - 2026-03-05
+
+### Added
+
+- Initial release baseline for `@khanglvm/outline-cli`.
+- Agent-optimized Outline CLI with deterministic JSON/NDJSON outputs, profile management, and batch invocation.
+- Mutation safety gates (`performAction`) and safe delete flow with read-token confirmation.

package/README.md

@@ -0,0 +1,244 @@
+# outline-cli
+
+`outline-cli` (alias `outline-agent`) is a Node.js CLI for the Outline API, designed for both human operators and AI agents.
+
+It prioritizes deterministic, machine-friendly output:
+
+- Stable JSON envelopes
+- Token-efficient `ids` and `summary` views
+- Batch operations to reduce API round trips
+- Safe mutation gates (`performAction: true`)
+- Automatic large-result offload to temp files
+
+## Quick Start
+
+Prerequisites:
+
+- Node.js `>=18.17`
+- An Outline workspace URL
+- An Outline API key (recommended auth mode)
+
+Run from npm without installing:
+
+```bash
+npx @khanglvm/outline-cli --help
+```
+
+Or install locally in this repo:
+
+```bash
+npm install
+node ./bin/outline-cli.js --help
+```
+
+Set up a profile (API key mode):
+
+```bash
+npx @khanglvm/outline-cli profile add prod \
+  --base-url https://app.getoutline.com \
+  --api-key "$OUTLINE_API_KEY" \
+  --set-default
+```
+
+Verify auth:
+
+```bash
+npx @khanglvm/outline-cli profile test prod --pretty
+```
+
+Run your first search:
+
+```bash
+npx @khanglvm/outline-cli invoke documents.search \
+  --args '{"query":"oncall runbook","mode":"semantic","limit":5,"view":"summary"}' \
+  --pretty
+```
+
+## Day-to-Day Usage
+
+Discover tools and contracts:
+
+```bash
+npx @khanglvm/outline-cli tools list
+npx @khanglvm/outline-cli tools contract documents.search --pretty
+npx @khanglvm/outline-cli tools contract all --result-mode inline
+```
+
+Read document metadata by id:
+
+```bash
+npx @khanglvm/outline-cli invoke documents.info \
+  --args '{"id":"<document-id>","view":"summary"}'
+```
+
+Create a document:
+
+```bash
+npx @khanglvm/outline-cli invoke documents.create \
+  --args '{"title":"Release Notes","text":"# Release Notes","publish":false,"view":"summary"}'
+```
+
+Update a document (mutation requires `performAction: true`):
+
+```bash
+npx @khanglvm/outline-cli invoke documents.update \
+  --args '{"id":"<document-id>","text":"\n\nUpdated by automation.","editMode":"append","performAction":true,"view":"summary"}'
+```
+
+Batch multiple calls:
+
+```bash
+npx @khanglvm/outline-cli batch --ops '[
+  {"tool":"collections.list","args":{"limit":5,"view":"summary"}},
+  {"tool":"documents.search","args":{"query":"incident","limit":5,"view":"ids"}}
+]'
+```
+
+## Safe Delete Flow
+
+Delete is guarded by read-token confirmation.
+
+1. Arm-delete read:
+
+```bash
+npx @khanglvm/outline-cli invoke documents.info \
+  --args '{"id":"<document-id>","armDelete":true,"view":"summary"}'
+```
+
+2. Copy the returned `deleteReadReceipt.token`, then delete:
+
+```bash
+npx @khanglvm/outline-cli invoke documents.delete \
+  --args '{"id":"<document-id>","readToken":"<token>","performAction":true}'
+```
+
+## Output Modes and Temp Files
+
+Output format:
+
+- `--output json` (default)
+- `--output ndjson` for stream-friendly parsing
+
+Result mode:
+
+- `--result-mode auto` (default): inline until payload is too large
+- `--result-mode inline`: always inline JSON
+- `--result-mode file`: always write to temp file and return file pointer
+
+Temp-file management:
+
+```bash
+npx @khanglvm/outline-cli tmp list
+npx @khanglvm/outline-cli tmp cat /absolute/path/from/result.json
+npx @khanglvm/outline-cli tmp gc --older-than-hours 24
+```
+
+## Profile Management
+
+Add password-mode profile:
+
+```bash
+npx @khanglvm/outline-cli profile add internal \
+  --base-url https://outline.company.com \
+  --auth-type password \
+  --username agent@company.com \
+  --password "$OUTLINE_PASSWORD"
+```
+
+Select default profile:
+
+```bash
+npx @khanglvm/outline-cli profile use prod
+```
+
+Improve AI profile routing metadata:
+
+```bash
+npx @khanglvm/outline-cli profile annotate prod \
+  --description "Production knowledge base" \
+  --append-keywords "prod,runbook,incident"
+
+npx @khanglvm/outline-cli profile enrich prod \
+  --query "incident escalation process" \
+  --titles "Incident Playbook,Escalation Matrix"
+```
+
+## AI Agent Mini Instructions
+
+Use this short operating pattern when an AI agent drives the CLI:
+
+1. Start with `tools contract all --result-mode inline`.
+2. Prefer `view:"ids"` or `view:"summary"` first; hydrate to `full` only when needed.
+3. Bundle independent reads into one `batch` call.
+4. For any mutation endpoint, explicitly set `performAction:true`.
+5. For delete, always run `documents.info` with `armDelete:true` first and pass the returned read token.
+6. If output is file-offloaded, read only the required fields via `tmp cat` + `jq`.
+
+For structured AI playbooks and scenario guides:
+
+```bash
+npx @khanglvm/outline-cli tools help ai-skills --view summary
+npx @khanglvm/outline-cli tools help ai-skills --scenario UC-12
+```
+
+## Testing (Live Environment)
+
+Set test credentials in local env file:
+
+```bash
+cp .env.test.example .env.test.local
+# set OUTLINE_TEST_BASE_URL and OUTLINE_TEST_API_KEY
+```
+
+Run checks:
+
+```bash
+npm run check
+npm test
+```
+
+Test rule in this repository:
+
+- Mutation tests create and clean up their own test documents.
+- Read-only tests may use site-wide data.
+
+## Release and Publish
+
+Standard release flow:
+
+```bash
+npm run release -- --bump patch
+```
+
+This flow performs:
+
+- Version bump
+- `CHANGELOG.md` update
+- Integrity refresh (`npm run integrity:refresh`)
+- Verification (`npm run check`, `npm test`)
+- `npm publish --access public`
+- Git commit, tag, and push to `origin`
+
+Prepare without publishing/pushing:
+
+```bash
+npm run release:prepare -- --bump patch
+```
+
+Release prerequisites:
+
+- Clean working tree (unless you intentionally pass `--allow-dirty`)
+- `OUTLINE_ENTRY_BUILD_KEY` available in environment or `.env.local`
+- npm auth ready (`npm login`)
+
+## Security Notes
+
+- Never commit real API keys.
+- Keep local secrets in untracked files such as `.env.test.local`.
+- Profile secrets are stored in OS keychain by default.
+
+## Reference Docs
+
+- Tool contracts: [`docs/TOOL_CONTRACTS.md`](docs/TOOL_CONTRACTS.md)
+- Agent rules for this repo: [`AGENTS.md`](AGENTS.md)
+- Release script: [`scripts/release.mjs`](scripts/release.mjs)

package/bin/outline-agent.js

@@ -0,0 +1,5 @@
+#!/usr/bin/env node
+import("./outline-cli.js").catch((err) => {
+  process.stderr.write(`${err?.stack || err}\n`);
+  process.exit(1);
+});

package/bin/outline-cli.js

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+import { assertEntryIntegrity } from "../src/entry-integrity.js";
+
+async function main() {
+  await assertEntryIntegrity();
+  const { run } = await import("../src/cli.js");
+  await run(process.argv);
+}
+
+main().catch((err) => {
+  process.stderr.write(`${err?.stack || err}\n`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@khanglvm/outline-cli",
+  "version": "0.1.1",
+  "description": "Agent-optimized CLI for Outline API",
+  "type": "module",
+  "bin": {
+    "outline-cli": "bin/outline-cli.js",
+    "outline-agent": "bin/outline-cli.js"
+  },
+  "scripts": {
+    "start": "node ./bin/outline-cli.js",
+    "check": "node ./bin/outline-cli.js --help",
+    "test": "node --test ./test/**/*.test.js",
+    "integrity:refresh": "node ./scripts/generate-entry-integrity.mjs",
+    "release": "node ./scripts/release.mjs",
+    "release:prepare": "node ./scripts/release.mjs --no-publish --no-push"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "dependencies": {
+    "@napi-rs/keyring": "^1.2.0",
+    "commander": "^13.1.0"
+  }
+}

package/scripts/generate-entry-integrity.mjs

@@ -0,0 +1,123 @@
+import crypto from "node:crypto";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const repoRoot = path.resolve(__dirname, "..");
+
+const bindingFile = path.join(repoRoot, "src", "entry-integrity-binding.generated.js");
+const manifestFile = path.join(repoRoot, "src", "entry-integrity-manifest.generated.js");
+
+const excludedFiles = new Set([
+  "src/entry-integrity-binding.generated.js",
+  "src/entry-integrity-manifest.generated.js",
+]);
+
+function digestHex(value) {
+  return crypto.createHash("sha256").update(value).digest("hex");
+}
+
+function canonicalManifest(files) {
+  return files
+    .map((item) => ({
+      path: item.path.replace(/\\/g, "/"),
+      sha256: item.sha256,
+    }))
+    .sort((a, b) => a.path.localeCompare(b.path))
+    .map((item) => `${item.path}:${item.sha256}`)
+    .join("\n");
+}
+
+async function walk(dirPath) {
+  const output = [];
+  const entries = await fs.readdir(dirPath, { withFileTypes: true });
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  for (const entry of entries) {
+    const abs = path.join(dirPath, entry.name);
+    if (entry.isDirectory()) {
+      output.push(...(await walk(abs)));
+      continue;
+    }
+    const rel = path.relative(repoRoot, abs).replace(/\\/g, "/");
+    if (!rel.endsWith(".js")) {
+      continue;
+    }
+    if (excludedFiles.has(rel)) {
+      continue;
+    }
+    output.push(rel);
+  }
+  return output;
+}
+
+async function hashFiles(files) {
+  const output = [];
+  for (const rel of files) {
+    const abs = path.join(repoRoot, rel);
+    const raw = await fs.readFile(abs);
+    output.push({
+      path: rel,
+      sha256: digestHex(raw),
+    });
+  }
+  return output;
+}
+
+function toBindingSource({ keySalt, keyId }) {
+  return `// Auto-generated by scripts/generate-entry-integrity.mjs
+export const ENTRY_INTEGRITY_BINDING = Object.freeze({
+  algorithm: "sha256-salted-manifest-v1",
+  keyId: ${JSON.stringify(keyId)},
+  keySalt: ${JSON.stringify(keySalt)},
+});
+`;
+}
+
+function toManifestSource({ generatedAt, signature, files }) {
+  return `// Auto-generated by scripts/generate-entry-integrity.mjs
+export const ENTRY_INTEGRITY_MANIFEST = Object.freeze({
+  version: 1,
+  algorithm: "sha256",
+  signatureAlgorithm: "sha256-salted-manifest-v1",
+  signature: ${JSON.stringify(signature)},
+  generatedAt: ${JSON.stringify(generatedAt)},
+  files: ${JSON.stringify(files, null, 2)},
+});
+`;
+}
+
+async function main() {
+  const buildKey = process.env.OUTLINE_ENTRY_BUILD_KEY || "dev-local-entry-integrity-key";
+  const keySalt = digestHex(buildKey);
+  const keyId = keySalt.slice(0, 12);
+
+  const srcFiles = await walk(path.join(repoRoot, "src"));
+  const hashes = await hashFiles(srcFiles);
+  const signature = digestHex(`${keySalt}\n${canonicalManifest(hashes)}`);
+
+  const generatedAt = new Date().toISOString();
+  await fs.writeFile(bindingFile, toBindingSource({ keySalt, keyId }), "utf8");
+  await fs.writeFile(
+    manifestFile,
+    toManifestSource({
+      generatedAt,
+      signature,
+      files: hashes,
+    }),
+    "utf8"
+  );
+
+  process.stdout.write(
+    `${JSON.stringify({
+      ok: true,
+      files: hashes.length,
+      manifestFile: path.relative(repoRoot, manifestFile),
+      bindingFile: path.relative(repoRoot, bindingFile),
+      keyId,
+      generatedAt,
+    }, null, 2)}\n`
+  );
+}
+
+await main();