@khanglvm/outline-cli 0.1.1

package/src/utils.js

@@ -0,0 +1,176 @@
+import fs from "node:fs/promises";
+
+export async function parseJsonArg({ json, file, name }) {
+  if (json && file) {
+    throw new Error(`Provide either --${name} or --${name}-file, not both`);
+  }
+
+  let raw;
+  if (file) {
+    raw = await fs.readFile(file, "utf8");
+  } else if (json) {
+    raw = json;
+  } else {
+    return undefined;
+  }
+
+  try {
+    return JSON.parse(raw);
+  } catch (err) {
+    throw new Error(`Invalid JSON for ${name}: ${err.message}`);
+  }
+}
+
+export function compactValue(value) {
+  if (Array.isArray(value)) {
+    return value
+      .map((item) => compactValue(item))
+      .filter((item) => item !== undefined);
+  }
+
+  if (value && typeof value === "object") {
+    const result = {};
+    for (const [key, child] of Object.entries(value)) {
+      const compacted = compactValue(child);
+      if (compacted === undefined) {
+        continue;
+      }
+      if (Array.isArray(compacted) && compacted.length === 0) {
+        continue;
+      }
+      if (
+        compacted &&
+        typeof compacted === "object" &&
+        !Array.isArray(compacted) &&
+        Object.keys(compacted).length === 0
+      ) {
+        continue;
+      }
+      result[key] = compacted;
+    }
+    if (Object.keys(result).length === 0) {
+      return undefined;
+    }
+    return result;
+  }
+
+  if (value === null || value === undefined) {
+    return undefined;
+  }
+  return value;
+}
+
+export function parseCsv(input) {
+  if (!input) {
+    return [];
+  }
+  return input
+    .split(",")
+    .map((part) => part.trim())
+    .filter(Boolean);
+}
+
+export function pickPath(obj, path) {
+  if (!path) {
+    return undefined;
+  }
+  const chunks = path.split(".").filter(Boolean);
+  let cur = obj;
+  for (const chunk of chunks) {
+    if (cur == null || typeof cur !== "object") {
+      return undefined;
+    }
+    cur = cur[chunk];
+  }
+  return cur;
+}
+
+export function projectObject(obj, fields) {
+  if (!fields || fields.length === 0) {
+    return obj;
+  }
+  const result = {};
+  for (const field of fields) {
+    const value = pickPath(obj, field);
+    if (value !== undefined) {
+      result[field] = value;
+    }
+  }
+  return result;
+}
+
+export function ensureStringArray(value, label) {
+  if (value === undefined || value === null) {
+    return undefined;
+  }
+
+  if (Array.isArray(value)) {
+    return value.map((item) => String(item));
+  }
+
+  if (typeof value === "string") {
+    return [value];
+  }
+
+  throw new Error(`${label} must be a string or string[]`);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+
+export function sanitizeFileToken(input) {
+  return String(input || "result").replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+export function toInteger(value, fallback) {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) {
+    throw new Error(`Invalid number: ${value}`);
+  }
+  return Math.trunc(parsed);
+}
+
+export function toBoolean(value, fallback = undefined) {
+  if (value === undefined || value === null || value === "") {
+    return fallback;
+  }
+  if (typeof value === "boolean") {
+    return value;
+  }
+  const normalized = String(value).toLowerCase();
+  if (["1", "true", "yes", "on"].includes(normalized)) {
+    return true;
+  }
+  if (["0", "false", "no", "off"].includes(normalized)) {
+    return false;
+  }
+  throw new Error(`Invalid boolean value: ${value}`);
+}
+
+export async function mapLimit(items, limit, fn) {
+  if (!Array.isArray(items) || items.length === 0) {
+    return [];
+  }
+  const concurrency = Math.max(1, Math.min(limit || 1, items.length));
+  const out = new Array(items.length);
+  let idx = 0;
+
+  async function worker() {
+    while (idx < items.length) {
+      const current = idx;
+      idx += 1;
+      out[current] = await fn(items[current], current);
+    }
+  }
+
+  await Promise.all(Array.from({ length: concurrency }, () => worker()));
+  return out;
+}

package/test/action-gate.unit.test.js

@@ -0,0 +1,157 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import fs from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+
+import { CliError } from "../src/errors.js";
+import {
+  assertPerformAction,
+  consumeDocumentDeleteReadReceipt,
+  getActionGateStorePath,
+  getDocumentDeleteReadReceipt,
+  isLikelyMutatingMethod,
+  issueDocumentDeleteReadReceipt,
+} from "../src/action-gate.js";
+
+test("assertPerformAction blocks when performAction is not true", () => {
+  assert.throws(
+    () =>
+      assertPerformAction({}, {
+        tool: "documents.update",
+        action: "update a document",
+      }),
+    (err) => {
+      assert.ok(err instanceof CliError);
+      assert.equal(err.details?.code, "ACTION_GATED");
+      return true;
+    }
+  );
+
+  assert.doesNotThrow(() =>
+    assertPerformAction({ performAction: true }, {
+      tool: "documents.update",
+      action: "update a document",
+    })
+  );
+});
+
+test("isLikelyMutatingMethod treats import/export paths as mutating", () => {
+  assert.equal(isLikelyMutatingMethod("documents.import"), true);
+  assert.equal(isLikelyMutatingMethod("documents.importFile"), true);
+  assert.equal(isLikelyMutatingMethod("/documents.export"), true);
+  assert.equal(isLikelyMutatingMethod("fileOperations.delete"), true);
+  assert.equal(isLikelyMutatingMethod("fileOperations.info"), false);
+});
+
+test("delete read receipt lifecycle: issue -> validate -> consume", async () => {
+  const previousTmp = process.env.OUTLINE_CLI_TMP_DIR;
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "outline-cli-action-gate-"));
+  process.env.OUTLINE_CLI_TMP_DIR = tmpDir;
+
+  try {
+    const issued = await issueDocumentDeleteReadReceipt({
+      profileId: "test-profile",
+      documentId: "doc-123",
+      revision: 7,
+      title: "Doc 123",
+      ttlSeconds: 600,
+    });
+
+    assert.ok(typeof issued.token === "string" && issued.token.length > 0);
+    assert.equal(issued.documentId, "doc-123");
+    assert.equal(issued.revision, 7);
+
+    const storePath = getActionGateStorePath();
+    assert.ok(storePath.startsWith(path.resolve(tmpDir)));
+
+    const fetched = await getDocumentDeleteReadReceipt({
+      token: issued.token,
+      profileId: "test-profile",
+      documentId: "doc-123",
+    });
+    assert.equal(fetched.documentId, "doc-123");
+    assert.equal(fetched.revision, 7);
+
+    await assert.rejects(
+      () =>
+        getDocumentDeleteReadReceipt({
+          token: issued.token,
+          profileId: "test-profile",
+          documentId: "doc-999",
+        }),
+      (err) => {
+        assert.ok(err instanceof CliError);
+        assert.equal(err.details?.code, "DELETE_READ_TOKEN_DOCUMENT_MISMATCH");
+        return true;
+      }
+    );
+
+    const consumed = await consumeDocumentDeleteReadReceipt(issued.token);
+    assert.equal(consumed, true);
+
+    await assert.rejects(
+      () =>
+        getDocumentDeleteReadReceipt({
+          token: issued.token,
+          profileId: "test-profile",
+          documentId: "doc-123",
+        }),
+      (err) => {
+        assert.ok(err instanceof CliError);
+        assert.equal(err.details?.code, "DELETE_READ_TOKEN_INVALID");
+        return true;
+      }
+    );
+  } finally {
+    if (previousTmp == null) {
+      delete process.env.OUTLINE_CLI_TMP_DIR;
+    } else {
+      process.env.OUTLINE_CLI_TMP_DIR = previousTmp;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});
+
+test("delete read receipt only accepts document-scoped token kind", async () => {
+  const previousTmp = process.env.OUTLINE_CLI_TMP_DIR;
+  const tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), "outline-cli-action-gate-kind-"));
+  process.env.OUTLINE_CLI_TMP_DIR = tmpDir;
+
+  try {
+    const issued = await issueDocumentDeleteReadReceipt({
+      profileId: "test-profile",
+      documentId: "doc-123",
+      revision: 7,
+      title: "Doc 123",
+      ttlSeconds: 600,
+    });
+
+    const storePath = getActionGateStorePath();
+    const raw = await fs.readFile(storePath, "utf8");
+    const parsed = JSON.parse(raw);
+    parsed.receipts[issued.token].kind = "webhooks.delete.read";
+    await fs.writeFile(storePath, `${JSON.stringify(parsed, null, 2)}\n`, "utf8");
+
+    await assert.rejects(
+      () =>
+        getDocumentDeleteReadReceipt({
+          token: issued.token,
+          profileId: "test-profile",
+          documentId: "doc-123",
+        }),
+      (err) => {
+        assert.ok(err instanceof CliError);
+        assert.equal(err.details?.code, "DELETE_READ_TOKEN_INVALID");
+        return true;
+      }
+    );
+  } finally {
+    if (previousTmp == null) {
+      delete process.env.OUTLINE_CLI_TMP_DIR;
+    } else {
+      process.env.OUTLINE_CLI_TMP_DIR = previousTmp;
+    }
+    await fs.rm(tmpDir, { recursive: true, force: true });
+  }
+});

package/test/agent-skills.unit.test.js

@@ -0,0 +1,52 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+
+import { getAgentSkillHelp, listHelpSections } from "../src/agent-skills.js";
+import { CliError } from "../src/errors.js";
+
+test("listHelpSections exposes ai-skills section", () => {
+  const sections = listHelpSections();
+  assert.ok(Array.isArray(sections));
+  assert.ok(sections.some((section) => section.id === "ai-skills"));
+});
+
+test("getAgentSkillHelp returns summary guidance by default", () => {
+  const payload = getAgentSkillHelp();
+
+  assert.equal(payload.section, "ai-skills");
+  assert.equal(payload.view, "summary");
+  assert.ok(payload.totalSkills >= 10);
+  assert.equal(payload.skills.length, payload.returnedSkills);
+  assert.ok(payload.globalGuidance?.principles?.length >= 1);
+  assert.ok(payload.skills.some((skill) => skill.id === "legacy_wiki_migration"));
+});
+
+test("getAgentSkillHelp filters by scenario and query", () => {
+  const byScenario = getAgentSkillHelp({ scenario: "uc-19" });
+  assert.equal(byScenario.returnedSkills, 1);
+  assert.equal(byScenario.skills[0].id, "oauth_compliance_audit");
+
+  const byQuery = getAgentSkillHelp({ query: "documents.import_file" });
+  assert.ok(byQuery.skills.some((skill) => skill.id === "legacy_wiki_migration"));
+});
+
+test("getAgentSkillHelp returns full skill payload and validates view", () => {
+  const payload = getAgentSkillHelp({
+    skill: "template_pipeline_execution",
+    view: "full",
+  });
+
+  assert.equal(payload.returnedSkills, 1);
+  assert.equal(payload.skills[0].id, "template_pipeline_execution");
+  assert.ok(Array.isArray(payload.skills[0].sequence));
+  assert.ok(payload.skills[0].sequence.some((step) => step.tool === "templates.extract_placeholders"));
+
+  assert.throws(
+    () => getAgentSkillHelp({ view: "compact" }),
+    (err) => {
+      assert.ok(err instanceof CliError);
+      assert.equal(err.details?.code, "AI_HELP_INVALID_VIEW");
+      return true;
+    }
+  );
+});

package/test/config-store.unit.test.js

@@ -0,0 +1,89 @@
+import test from "node:test";
+import assert from "node:assert/strict";
+import {
+  buildProfile,
+  normalizeBaseUrlWithHints,
+  suggestProfileMetadata,
+  suggestProfiles,
+} from "../src/config-store.js";
+
+test("normalizeBaseUrlWithHints auto-corrects official and document URLs", () => {
+  const official = normalizeBaseUrlWithHints("https://www.getoutline.com");
+  assert.equal(official.baseUrl, "https://app.getoutline.com");
+  assert.equal(official.corrected, true);
+  assert.ok(official.corrections.includes("mapped_official_outline_host"));
+
+  const docUrl = normalizeBaseUrlWithHints(
+    "https://handbook.acme.example/doc/event-tracking-data-A7hLXuHZJl#d-A7hLXuHZJl"
+  );
+  assert.equal(docUrl.baseUrl, "https://handbook.acme.example");
+  assert.equal(docUrl.corrected, true);
+  assert.ok(docUrl.corrections.includes("trimmed_ui_path"));
+
+  const reverseProxy = normalizeBaseUrlWithHints("https://wiki.example.com/outline/api/auth.info");
+  assert.equal(reverseProxy.baseUrl, "https://wiki.example.com/outline");
+  assert.ok(reverseProxy.corrections.includes("trimmed_path_after_api"));
+});
+
+test("buildProfile persists optional description and keywords metadata", () => {
+  const profile = buildProfile({
+    id: "acme-handbook",
+    name: "Acme Handbook",
+    description: "Tracking and campaign specs",
+    keywords: ["tracking", "campaign", "tracking", " event "],
+    baseUrl: "https://handbook.acme.example/doc/event-tracking-data-A7hLXuHZJl",
+    authType: "apiKey",
+    apiKey: "ol_api_example",
+  });
+
+  assert.equal(profile.description, "Tracking and campaign specs");
+  assert.deepEqual(profile.keywords, ["tracking", "campaign", "event"]);
+  assert.equal(profile.baseUrl, "https://handbook.acme.example");
+});
+
+test("suggestProfiles ranks profiles by keywords/description/host signals", () => {
+  const config = {
+    version: 1,
+    defaultProfile: "engineering",
+    profiles: {
+      engineering: {
+        name: "Engineering",
+        baseUrl: "https://wiki.example.com",
+        description: "Runbooks and incident policy",
+        keywords: ["incident", "runbook", "sre"],
+        auth: { type: "apiKey", apiKey: "ol_api_eng" },
+      },
+      marketing: {
+        name: "Acme Handbook",
+        baseUrl: "https://handbook.acme.example",
+        description: "Marketing campaign and event tracking handbook",
+        keywords: ["tracking", "campaign", "analytics"],
+        auth: { type: "apiKey", apiKey: "ol_api_marketing" },
+      },
+    },
+  };
+
+  const result = suggestProfiles(config, "campaign tracking handbook", { limit: 2 });
+  assert.equal(result.matches.length, 2);
+  assert.equal(result.matches[0].id, "marketing");
+  assert.ok(result.matches[0].score > result.matches[1].score);
+  assert.ok(Array.isArray(result.matches[0].matchedOn));
+});
+
+test("suggestProfileMetadata can generate and enrich metadata from hints", () => {
+  const next = suggestProfileMetadata({
+    id: "acme-handbook",
+    name: "Acme Handbook",
+    baseUrl: "https://handbook.acme.example",
+    hints: [
+      "implement tracking collection for landing page",
+      "campaign detail page",
+    ],
+  }, { maxKeywords: 12 });
+
+  assert.ok(next.description.includes("Acme Handbook"));
+  assert.ok(next.keywords.includes("tracking"));
+  assert.ok(next.keywords.includes("landing page"));
+  assert.ok(next.keywords.includes("campaign detail"));
+  assert.equal(next.generated.hintsUsed, 2);
+});