knowingdog 0.0.0-stage → 0.2.0

package/knowing.mjs

@@ -0,0 +1,383 @@
+#!/usr/bin/env node
+import { randomUUID, randomBytes, createHash } from "node:crypto";
+import { readFile, writeFile, mkdir, realpath, lstat } from "node:fs/promises";
+import { resolve, dirname, relative, sep, join } from "node:path";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+import { execFileSync } from "node:child_process";
+import { pathToFileURL } from "node:url";
+
+export function spaceEndpoint(value) {
+  const url = new URL(value);
+  if (
+    url.username ||
+    url.password ||
+    url.search ||
+    url.hash ||
+    (url.protocol !== "https:" &&
+      !(
+        url.protocol === "http:" &&
+        ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname)
+      ))
+  )
+    throw new Error("Use an HTTPS space URL (or localhost for development).");
+  const match = url.pathname.match(/^\/s\/([a-z0-9-]+)\/?$/);
+  if (!match)
+    throw new Error(
+      "Use the default space URL, https://your-knowing-host/s/space-slug.",
+    );
+  return new URL(`/api/knowing/spaces/${match[1]}/mcp`, url.origin);
+}
+const publishingTools = new Set([
+  "get_publishing_info",
+  "sync_space",
+  "publish_release",
+]);
+// knowing-skills.mjs saves `knowing login` customer tokens per site origin,
+// and the last login's site as default-site.json.
+async function savedConfiguration(configDir, name) {
+  try {
+    return JSON.parse(
+      await readFile(
+        join(
+          configDir
+            ? resolve(configDir)
+            : join(homedir(), ".config", "knowing-skills"),
+          name,
+        ),
+        "utf8",
+      ),
+    );
+  } catch (error) {
+    if (error.code !== "ENOENT") throw error;
+    return {};
+  }
+}
+async function savedCustomerToken(space, configDir) {
+  const { token } = await savedConfiguration(
+    configDir,
+    `${createHash("sha256").update(new URL(space).origin).digest("hex")}.json`,
+  );
+  if (token?.startsWith("knc_")) return token;
+  if (token)
+    process.stderr.write(
+      "Run knowing login again to use your Knowing account here.\n",
+    );
+  return undefined;
+}
+function post(endpoint, message, token) {
+  return fetch(endpoint, {
+    method: "POST",
+    redirect: "error",
+    headers: {
+      "Content-Type": "application/json",
+      Accept: "application/json, text/event-stream",
+      "MCP-Protocol-Version": "2025-11-25",
+      ...(token ? { Authorization: `Bearer ${token}` } : {}),
+    },
+    body: JSON.stringify(message),
+    signal: AbortSignal.timeout(290000),
+  });
+}
+export async function rpc(endpoint, message, token) {
+  const response = await post(endpoint, message, token);
+  if (response.status === 202) return null;
+  if (!response.ok)
+    throw new Error(
+      `Knowing request failed (${response.status}). No automatic retry was made.`,
+    );
+  const result = await response.json();
+  if (result.error) throw new Error(result.error.message);
+  return result;
+}
+const call = async (endpoint, name, args, token) => {
+  const response = await rpc(
+    endpoint,
+    {
+      jsonrpc: "2.0",
+      id: randomUUID(),
+      method: "tools/call",
+      params: { name, arguments: args },
+    },
+    token,
+  );
+  if (response.result.isError)
+    throw new Error(
+      response.result.content.map((item) => item.text).join("\n"),
+    );
+  return response.result.structuredContent;
+};
+const option = (args, name) => {
+  const index = args.indexOf(`--${name}`);
+  if (index < 0) return undefined;
+  if (!args[index + 1] || args[index + 1].startsWith("--"))
+    throw new Error(`--${name} requires a value.`);
+  return args[index + 1];
+};
+export function workflows(space, digest, branch) {
+  spaceEndpoint(space);
+  if (!/^[0-9a-f]{64}$/.test(digest)) throw new Error("Invalid CLI digest.");
+  if (!branch || branch.includes("\n"))
+    throw new Error("Invalid published branch.");
+  const setup = `      - uses: actions/checkout@v4\n        with:\n          persist-credentials: false\n      - uses: actions/setup-node@v4\n        with:\n          node-version: '24'\n      - name: Verify pinned Knowing CLI\n        run: |\n          echo '${digest}  .github/knowing.mjs' | sha256sum --check\n          cp .github/knowing.mjs "$RUNNER_TEMP/knowing.mjs"\n`;
+  const common = `permissions:\n  contents: read\nconcurrency:\n  group: knowing-${"${{ github.workflow }}"}-${"${{ github.ref }}"}\n  cancel-in-progress: false\njobs:\n  knowing:\n    runs-on: ubuntu-latest\n    steps:\n${setup}`;
+  return {
+    "knowing-docs.yml": `name: Knowing docs and agent\non:\n  workflow_dispatch:\n    inputs:\n      question:\n        description: 'Optional question for the space agent (uses space AI usage)'\n        required: false\n        type: string\n${common}      - name: Read docs or ask the agent\n        env:\n          KNOWING_SPACE: ${JSON.stringify(space)}\n          QUESTION: ${"${{ inputs.question }}"}\n        run: |\n          if [ -n "$QUESTION" ]; then\n            node "$RUNNER_TEMP/knowing.mjs" ask --space "$KNOWING_SPACE" --question "$QUESTION" > knowing-result.json\n          else\n            node "$RUNNER_TEMP/knowing.mjs" docs --space "$KNOWING_SPACE" > knowing-result.json\n          fi\n      - uses: actions/upload-artifact@v4\n        with:\n          name: knowing-result\n          path: knowing-result.json\n`,
+    "knowing-publish.yml": `name: Publish Knowing space\non:\n  push:\n    branches: [${JSON.stringify(branch)}]\n  workflow_dispatch:\n    inputs:\n      publish_release:\n        description: 'Publish the source-defined release at this commit'\n        required: false\n        default: false\n        type: boolean\n${common}      - name: Publish existing repository pages\n        env:\n          KNOWING_SPACE: ${JSON.stringify(space)}\n          KNOWING_TOKEN: ${"${{ secrets.KNOWING_PUBLISH_TOKEN }}"}\n          PUBLISH_RELEASE: ${"${{ inputs.publish_release }}"}\n        run: |\n          if [ "$PUBLISH_RELEASE" = "true" ]; then\n            node "$RUNNER_TEMP/knowing.mjs" publish --space "$KNOWING_SPACE" --branch "$GITHUB_REF_NAME" --commit "$GITHUB_SHA"\n          else\n            node "$RUNNER_TEMP/knowing.mjs" sync --space "$KNOWING_SPACE"\n          fi\n`,
+  };
+}
+export async function writeNewFile(root, file, content) {
+  const base = await realpath(root);
+  const target = resolve(base, file);
+  if (!relative(base, target) || relative(base, target).startsWith(`..${sep}`))
+    throw new Error("File must stay inside the repository.");
+  let path = base;
+  for (const part of relative(base, dirname(target))
+    .split(sep)
+    .filter(Boolean)) {
+    path = resolve(path, part);
+    await mkdir(path).catch((error) => {
+      if (error.code !== "EEXIST") throw error;
+    });
+    if ((await lstat(path)).isSymbolicLink())
+      throw new Error("Refusing to write through a symbolic link.");
+  }
+  await writeFile(target, content, { flag: "wx", mode: 0o644 });
+}
+function github(args, input) {
+  return execFileSync("gh", args, {
+    encoding: "utf8",
+    ...(input ? { input } : {}),
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+}
+function repositoryName(url) {
+  return url.match(/github\.com[:/]([^/]+\/[^/]+?)(?:\.git)?$/)?.[1];
+}
+export async function main(args = process.argv.slice(2)) {
+  const command = args[0];
+  if (!command || command === "help" || args.includes("--help")) {
+    process.stdout.write(
+      "Knowing: docs, search, ask, sync, publish, init-ci, mcp, mcp-config\nUse --space https://your-knowing-host/s/your-space. Reading sends your saved knowing login, or KNOWING_CUSTOMER_TOKEN to the KNOWING_SITE origin. Publishing uses KNOWING_TOKEN from the environment.\n",
+    );
+    return;
+  }
+  const space = option(args, "space") ?? process.env.KNOWING_SPACE;
+  if (!space) throw new Error("--space is required.");
+  const endpoint = spaceEndpoint(space);
+  const token = process.env.KNOWING_TOKEN;
+  const configDir = option(args, "config-dir");
+  // KNOWING_CUSTOMER_TOKEN is account-wide, so it only goes to a configured
+  // site, never to whatever origin --space names.
+  const customerToken = async () => {
+    const environment = process.env.KNOWING_CUSTOMER_TOKEN;
+    const configured = [
+      process.env.KNOWING_SITE,
+      process.env.KNOWING_SPACE,
+      (await savedConfiguration(configDir, "default-site.json")).origin,
+    ].filter((value) => value && URL.canParse(value));
+    if (
+      environment &&
+      configured.some((value) => new URL(value).origin === endpoint.origin)
+    )
+      return environment;
+    const saved = await savedCustomerToken(space, configDir);
+    if (environment && !saved)
+      process.stderr.write(
+        `KNOWING_CUSTOMER_TOKEN was not sent to ${endpoint.origin}: it only goes to your Knowing site, set by KNOWING_SITE or your last knowing login.\n`,
+      );
+    return saved;
+  };
+  if (command === "mcp") {
+    const customer = await customerToken();
+    const lines = createInterface({
+      input: process.stdin,
+      crlfDelay: Infinity,
+    });
+    for await (const line of lines) {
+      if (line.length > 32000) {
+        process.stderr.write("MCP message too large.\n");
+        continue;
+      }
+      let message;
+      try {
+        message = JSON.parse(line);
+      } catch {
+        process.stdout.write(
+          JSON.stringify({
+            jsonrpc: "2.0",
+            id: null,
+            error: { code: -32700, message: "Parse error" },
+          }) + "\n",
+        );
+        continue;
+      }
+      try {
+        const name =
+          message?.method === "tools/call" ? message.params?.name : undefined;
+        // Each call carries the one token its tool accepts; discovery lists publishing tools when KNOWING_TOKEN is set.
+        const credential = name
+          ? publishingTools.has(name)
+            ? token
+            : customer
+          : (token ?? customer);
+        const response = await post(endpoint, message, credential);
+        if (response.status === 202) continue;
+        const reply = await response.json();
+        if (reply?.jsonrpc !== "2.0") throw new Error("Invalid response");
+        process.stdout.write(JSON.stringify(reply) + "\n");
+      } catch {
+        if (message?.id !== undefined)
+          process.stdout.write(
+            JSON.stringify({
+              jsonrpc: "2.0",
+              id: message.id,
+              error: {
+                code: -32603,
+                message: "Knowing request failed. No automatic retry was made.",
+              },
+            }) + "\n",
+          );
+      }
+    }
+    return;
+  }
+  if (command === "mcp-config") {
+    process.stdout.write(
+      JSON.stringify(
+        {
+          mcpServers: {
+            [endpoint.pathname.split("/").at(-2)]: {
+              command: "node",
+              args: [
+                resolve(process.argv[1]),
+                "mcp",
+                "--space",
+                space,
+                ...(configDir ? ["--config-dir", resolve(configDir)] : []),
+              ],
+            },
+          },
+        },
+        null,
+        2,
+      ) + "\n",
+    );
+    process.stderr.write(
+      `This server signs in with your saved knowing login for ${endpoint.origin}. Elsewhere, set KNOWING_CUSTOMER_TOKEN and KNOWING_SITE=${endpoint.origin} (or KNOWING_TOKEN for publishing) in your MCP client's environment or secret settings. Never put a token in the URL or this configuration.\n`,
+    );
+    return;
+  }
+  if (command === "init-ci") {
+    if (endpoint.protocol !== "https:")
+      throw new Error("GitHub Actions requires your hosted HTTPS Knowing URL.");
+    const root = execFileSync("git", ["rev-parse", "--show-toplevel"], {
+      encoding: "utf8",
+    }).trim();
+    const remote = execFileSync("git", ["remote", "get-url", "origin"], {
+      encoding: "utf8",
+    }).trim();
+    const repository = repositoryName(remote);
+    if (!repository)
+      throw new Error("The repository must have a GitHub origin.");
+    const info = await call(endpoint, "get_publishing_info", {}, token);
+    if (repository.toLowerCase() !== info.repository.toLowerCase())
+      throw new Error(
+        "This repository is not the space’s connected repository.",
+      );
+    const script = await readFile(process.argv[1], "utf8");
+    const digest = createHash("sha256").update(script).digest("hex");
+    const files = workflows(space, digest, info.branch);
+    files["../knowing.mjs"] = script;
+    for (const name of Object.keys(files)) {
+      try {
+        await lstat(resolve(root, ".github/workflows", name));
+        throw new Error(
+          `${name} already exists. Review it before replacing it.`,
+        );
+      } catch (error) {
+        if (error.code !== "ENOENT") throw error;
+      }
+    }
+    for (const [name, content] of Object.entries(files))
+      await writeNewFile(root, `.github/workflows/${name}`, content);
+    process.stdout.write(
+      "Created two workflows and the pinned .github/knowing.mjs CLI.\n",
+    );
+    if (args.includes("--set-secret")) {
+      if (!token)
+        throw new Error("KNOWING_TOKEN is required to set the secret.");
+      github(
+        ["secret", "set", "KNOWING_PUBLISH_TOKEN", "--repo", repository],
+        token,
+      );
+      process.stdout.write("Set KNOWING_PUBLISH_TOKEN in GitHub.\n");
+    }
+    try {
+      const secrets = JSON.parse(
+        github(["secret", "list", "--repo", repository, "--json", "name"]),
+      );
+      process.stdout.write(
+        secrets.some((secret) => secret.name === "KNOWING_PUBLISH_TOKEN")
+          ? "[done] Publishing secret exists.\n"
+          : "[todo] Set KNOWING_PUBLISH_TOKEN; run init-ci with --set-secret on a fresh setup or gh secret set KNOWING_PUBLISH_TOKEN.\n",
+      );
+    } catch {
+      process.stdout.write(
+        "[todo] Sign into gh and check the KNOWING_PUBLISH_TOKEN repository secret.\n",
+      );
+    }
+    process.stdout.write(
+      "[todo] Review, commit and push the workflows.\n[info] Workflows need only contents: read. They do not open pull requests. Publishing token expires after 90 days; rotate it in Channels and replace the secret.\n",
+    );
+    return;
+  }
+  const repository = process.env.GITHUB_REPOSITORY;
+  let name, input;
+  if (command === "docs") {
+    name = option(args, "page") ? "read_page" : "list_pages";
+    input = option(args, "page") ? { page: option(args, "page") } : {};
+  } else if (command === "search") {
+    name = "search_docs";
+    input = { query: option(args, "query") };
+  } else if (command === "ask") {
+    name = "ask_agent";
+    input = {
+      question: option(args, "question"),
+      requestId: randomUUID(),
+      visitorToken: randomBytes(32).toString("base64url"),
+    };
+  } else if (command === "sync") {
+    name = "sync_space";
+    input = repository ? { repository } : {};
+  } else if (command === "publish") {
+    name = "publish_release";
+    input = {
+      branch: option(args, "branch"),
+      commit: option(args, "commit"),
+      version: option(args, "version"),
+      license: option(args, "license"),
+      ...(repository ? { repository } : {}),
+    };
+  } else throw new Error(`Unknown command: ${command}`);
+  process.stdout.write(
+    JSON.stringify(
+      await call(
+        endpoint,
+        name,
+        input,
+        publishingTools.has(name) ? token : await customerToken(),
+      ),
+      null,
+      2,
+    ) + "\n",
+  );
+}
+if (
+  process.argv[1] &&
+  import.meta.url === pathToFileURL(await realpath(process.argv[1])).href
+)
+  main().catch((error) => {
+    process.stderr.write(`${error.message}\n`);
+    process.exitCode = 1;
+  });

package/package.json

@@ -1,6 +1,23 @@
 {
   "name": "knowingdog",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "Install source-defined Knowing skills and agents and configure GitHub Actions.",
+  "type": "module",
+  "bin": {
+    "knowing": "knowing-cli.mjs"
+  },
+  "files": [
+    "knowing-cli.mjs",
+    "knowing-skills.mjs",
+    "knowing.mjs"
+  ],
+  "engines": {
+    "node": ">=24"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/BrickspaceLab/knowing.git",
+    "directory": "scripts"
+  }
+}