@systemdox/mcp-server 0.1.45 → 0.1.46

package/dist/lib/team-setup-files.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The files the team setup keeps on a member's computer (ADR-217,
+ * specs/changes/team-setup/contract.md "Files on a member's computer"):
+ *
+ * - `~/.claude/systemdox/credentials.json`: `{ "<workspace>": { "apiKey" } }`,
+ *   readable by the member alone (mode 600; on Windows an ACL for the member
+ *   alone);
+ * - `~/.claude/systemdox/<workspace>/state.json`: the installed versions and
+ *   hashes, each memory project's base manifest and version, the accepted
+ *   SHA-256s. Never a value and never an answer about a person;
+ * - `~/.claude/systemdox/<workspace>/plugin/<n>/`: plugin version n, unpacked.
+ *
+ * Every path starts at `homeDir()`, the one place the home folder is read, so
+ * a test points HOME (USERPROFILE on Windows) at a temporary folder.
+ *
+ * Also here: the API key's order (SYSTEMDOX_API_KEY, then credentials.json for
+ * the workspace) and `marketplace-auth`, the marketplace's `headersHelper`,
+ * which reads only these files and the environment.
+ */
+/** A workspace is a tenant slug (openapi Slug): it names a folder, so nothing
+ * else is accepted. */
+export declare function isWorkspace(value: unknown): value is string;
+/** The member's home folder: `os.homedir()`, which reads HOME (USERPROFILE on
+ * Windows) on every call. */
+export declare function homeDir(): string;
+export declare function systemdoxDir(): string;
+export declare function credentialsPath(): string;
+export declare function workspaceDir(workspace: string): string;
+export declare function statePath(workspace: string): string;
+export declare function pluginRoot(workspace: string): string;
+export declare function pluginDir(workspace: string, version: number): string;
+export type Credentials = Record<string, {
+    apiKey: string;
+}>;
+export declare function readCredentials(): Promise<Credentials>;
+/** Restrict `path` to the member alone: mode 600, and on Windows an ACL with
+ * inheritance removed and one full-control entry for the current user. */
+export declare function restrictToMember(path: string): Promise<void>;
+/** Save the key for `workspace` in credentials.json, readable by the member alone. */
+export declare function writeCredentials(workspace: string, apiKey: string): Promise<void>;
+/** The key for `workspace`, in the contract's order: SYSTEMDOX_API_KEY, then
+ * credentials.json for the workspace. Undefined when neither has one. */
+export declare function apiKeyFor(workspace: string, env?: NodeJS.ProcessEnv): Promise<string | undefined>;
+/** SYSTEMDOX_API_URL or the default, https only (throws otherwise). */
+export declare function apiUrlFrom(env?: NodeJS.ProcessEnv): string;
+export interface TeamSetupState {
+    /** Plugin versions unpacked under plugin/<n>/, keyed by n: the zip's SHA-256. */
+    plugin?: Record<string, {
+        sha256: string;
+        installedAt: string;
+    }>;
+    /** The team instructions as last installed (`setup`). */
+    instructions?: {
+        version: number;
+        sha256: string;
+    };
+    /** Each memory project's base: the version synced last and its manifest. */
+    memory?: Record<string, {
+        version: number;
+        manifest: Record<string, string>;
+    }>;
+    /** The SHA-256s the member accepted (`setup --yes`). */
+    accepted?: string[];
+}
+export declare function readState(workspace: string): Promise<TeamSetupState>;
+export declare function writeState(workspace: string, state: TeamSetupState): Promise<void>;
+/** Read, change and write state.json in one step. */
+export declare function updateState(workspace: string, change: (state: TeamSetupState) => void): Promise<TeamSetupState>;
+/** Remove a folder this code made (a temporary unpack). */
+export declare function removeFolder(path: string): Promise<void>;
+/**
+ * The workspace a marketplace URL is for, or undefined when the key must not
+ * go there: the URL must be https, on the origin of the API URL, with a path
+ * `<api path>/v1/team-setup/<workspace>/marketplace.json`.
+ */
+export declare function marketplaceWorkspace(marketplaceUrl: string, apiUrl: string): string | undefined;
+export interface CommandIo {
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/**
+ * `marketplace-auth`: Claude Code runs it with CLAUDE_CODE_MARKETPLACE_URL
+ * set. On a SystemDox marketplace URL it prints exactly
+ * `{"Authorization":"Bearer <key>"}` for that workspace and returns 0;
+ * otherwise nothing on stdout, the URL on stderr, and 1. No network call,
+ * nothing written.
+ */
+export declare function runMarketplaceAuth(io: CommandIo, env?: NodeJS.ProcessEnv): Promise<number>;

package/dist/lib/team-setup-files.js

@@ -0,0 +1,191 @@
+#!/usr/bin/env node
+
+// src/lib/team-setup-files.ts
+import { execFile } from "child_process";
+import { chmod, mkdir, readFile, rename, rm, writeFile } from "fs/promises";
+import { homedir, userInfo } from "os";
+import { dirname, join } from "path";
+import { promisify } from "util";
+
+// src/lib/config.ts
+var API_URL_DEFAULT = "https://api.puglieseweb.com/systemdox";
+function requireHttpsApiUrl(apiUrl) {
+  let parsed;
+  try {
+    parsed = new URL(apiUrl);
+  } catch {
+    throw new Error(
+      `SYSTEMDOX_API_URL is not a valid URL: ${apiUrl}`
+    );
+  }
+  if (parsed.protocol !== "https:") {
+    throw new Error(
+      `SYSTEMDOX_API_URL must use https:// \u2014 refusing to send the API key over ${parsed.protocol}// in cleartext. Got: ${apiUrl}`
+    );
+  }
+  return apiUrl;
+}
+
+// src/lib/team-setup-files.ts
+var SLUG_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+function isWorkspace(value) {
+  return typeof value === "string" && value.length <= 64 && SLUG_RE.test(value);
+}
+function homeDir() {
+  return homedir();
+}
+function systemdoxDir() {
+  return join(homeDir(), ".claude", "systemdox");
+}
+function credentialsPath() {
+  return join(systemdoxDir(), "credentials.json");
+}
+function workspaceDir(workspace) {
+  if (!isWorkspace(workspace)) throw new Error(`${JSON.stringify(workspace)} is not a workspace name`);
+  return join(systemdoxDir(), workspace);
+}
+function statePath(workspace) {
+  return join(workspaceDir(workspace), "state.json");
+}
+function pluginRoot(workspace) {
+  return join(workspaceDir(workspace), "plugin");
+}
+function pluginDir(workspace, version) {
+  return join(pluginRoot(workspace), String(version));
+}
+async function readJson(path, empty) {
+  let text;
+  try {
+    text = await readFile(path, "utf8");
+  } catch (e) {
+    if (e.code === "ENOENT") return empty;
+    throw e;
+  }
+  try {
+    return JSON.parse(text);
+  } catch {
+    throw new Error(`${path} is not valid JSON: fix or remove it, then run this again`);
+  }
+}
+async function writeJsonAtomically(path, value, mode) {
+  await mkdir(dirname(path), { recursive: true });
+  const tmp = `${path}.${process.pid}.tmp`;
+  await writeFile(tmp, JSON.stringify(value, null, 2) + "\n", mode === void 0 ? "utf8" : { encoding: "utf8", mode });
+  await rename(tmp, path);
+}
+async function readCredentials() {
+  return readJson(credentialsPath(), {});
+}
+var run = promisify(execFile);
+async function restrictToMember(path) {
+  await chmod(path, 384);
+  if (process.platform === "win32") {
+    await run("icacls", [path, "/inheritance:r", "/grant:r", `${userInfo().username}:F`], { windowsHide: true });
+  }
+}
+async function writeCredentials(workspace, apiKey) {
+  if (!isWorkspace(workspace)) throw new Error(`${JSON.stringify(workspace)} is not a workspace name`);
+  if (!apiKey) throw new Error("an API key is required");
+  const path = credentialsPath();
+  const credentials = await readCredentials();
+  credentials[workspace] = { apiKey };
+  await writeJsonAtomically(path, credentials, 384);
+  await restrictToMember(path);
+}
+async function apiKeyFor(workspace, env = process.env) {
+  if (env.SYSTEMDOX_API_KEY) return env.SYSTEMDOX_API_KEY;
+  const entry = (await readCredentials())[workspace];
+  return typeof entry?.apiKey === "string" && entry.apiKey ? entry.apiKey : void 0;
+}
+function apiUrlFrom(env = process.env) {
+  return requireHttpsApiUrl(env.SYSTEMDOX_API_URL || API_URL_DEFAULT);
+}
+async function readState(workspace) {
+  return readJson(statePath(workspace), {});
+}
+async function writeState(workspace, state) {
+  await writeJsonAtomically(statePath(workspace), state);
+}
+async function updateState(workspace, change) {
+  const state = await readState(workspace);
+  change(state);
+  await writeState(workspace, state);
+  return state;
+}
+async function removeFolder(path) {
+  await rm(path, { recursive: true, force: true });
+}
+function escapeRegExp(s) {
+  return s.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+function marketplaceWorkspace(marketplaceUrl, apiUrl) {
+  let url;
+  let api;
+  try {
+    url = new URL(marketplaceUrl);
+    api = new URL(requireHttpsApiUrl(apiUrl));
+  } catch {
+    return void 0;
+  }
+  if (url.protocol !== "https:" || url.origin !== api.origin || url.username || url.password) return void 0;
+  const base = api.pathname.replace(/\/+$/, "");
+  const m = new RegExp(`^${escapeRegExp(base)}/v1/team-setup/([^/]+)/marketplace\\.json$`).exec(url.pathname);
+  return m && isWorkspace(m[1]) ? m[1] : void 0;
+}
+async function runMarketplaceAuth(io, env = process.env) {
+  const url = env.CLAUDE_CODE_MARKETPLACE_URL;
+  if (!url) {
+    io.err("marketplace-auth: CLAUDE_CODE_MARKETPLACE_URL is not set; Claude Code sets it when it fetches a marketplace.");
+    return 1;
+  }
+  let apiUrl;
+  try {
+    apiUrl = apiUrlFrom(env);
+  } catch (e) {
+    io.err(`marketplace-auth: ${e.message}`);
+    return 1;
+  }
+  const workspace = marketplaceWorkspace(url, apiUrl);
+  if (!workspace) {
+    io.err(
+      `marketplace-auth: refusing to give a SystemDox key for ${url}: it is not a SystemDox team marketplace on ${apiUrl}`
+    );
+    return 1;
+  }
+  let key;
+  try {
+    key = await apiKeyFor(workspace, env);
+  } catch (e) {
+    io.err(`marketplace-auth: ${e.message}`);
+    return 1;
+  }
+  if (!key) {
+    io.err(
+      `marketplace-auth: no SystemDox key for ${workspace}. Set SYSTEMDOX_API_KEY, or run npx -y @systemdox/mcp-server setup.`
+    );
+    return 1;
+  }
+  io.out(JSON.stringify({ Authorization: `Bearer ${key}` }));
+  return 0;
+}
+export {
+  apiKeyFor,
+  apiUrlFrom,
+  credentialsPath,
+  homeDir,
+  isWorkspace,
+  marketplaceWorkspace,
+  pluginDir,
+  pluginRoot,
+  readCredentials,
+  readState,
+  removeFolder,
+  restrictToMember,
+  runMarketplaceAuth,
+  statePath,
+  systemdoxDir,
+  updateState,
+  workspaceDir,
+  writeCredentials,
+  writeState
+};

package/dist/lib/team-setup-types.d.ts

@@ -0,0 +1,153 @@
+/**
+ * The team-setup shapes of specs/changes/team-setup/openapi.yaml
+ * (components.schemas), as the client reads and sends them, and the two
+ * enumerations it checks locally (the parts, the PersonId pattern).
+ */
+export declare const PARTS: readonly ["hooks", "mcp", "agents", "commands", "instructions"];
+export type PartName = (typeof PARTS)[number];
+export interface FileIn {
+    path: string;
+    content: string;
+}
+export interface FileMeta {
+    path: string;
+    bytes: number;
+    sha256: string;
+}
+export interface PartVersionSummary {
+    part: PartName;
+    version: number;
+    publishedAt: string;
+    publishedBy: string;
+    files: FileMeta[];
+}
+export interface PartDetail {
+    part: PartName;
+    latestVersion: number;
+    versions: PartVersionSummary[];
+}
+export interface PartVersionFiles extends Omit<PartVersionSummary, "files"> {
+    files: (FileMeta & {
+        content: string;
+    })[];
+}
+export interface PartPublished extends PartVersionSummary {
+    /** Absent for `instructions`. */
+    pluginVersion?: number;
+    /** `mcp` only. */
+    replacedValues?: {
+        server: string;
+        field: "env" | "headers";
+        name: string;
+    }[];
+}
+export interface PluginVersion {
+    version: number;
+    sha256: string;
+    bytes: number;
+    createdAt: string;
+    createdBy?: string;
+    parts: Record<string, number>;
+    skills: Record<string, number>;
+    hookCommands?: string[];
+    mcpServers?: {
+        name: string;
+        command?: string;
+        args?: string[];
+        url?: string;
+    }[];
+    command: string;
+}
+export interface Marketplace {
+    name: string;
+    owner: {
+        name: string;
+    };
+    plugins: {
+        name: string;
+        version: string;
+        description: string;
+        source: {
+            source: "command";
+            command: string;
+            timeout: number;
+        };
+    }[];
+}
+export interface MemoryProjectSummary {
+    project: string;
+    latestVersion: number;
+    fileCount: number;
+    bytes: number;
+    updatedAt: string;
+    spaceId: string;
+}
+export interface TeamSetup {
+    workspace: string;
+    minClaudeCodeVersion: string;
+    marketplaceUrl: string;
+    plugin?: PluginVersion;
+    parts: Record<string, number>;
+    skills: string[];
+    memory: MemoryProjectSummary[];
+}
+/** `{path: sha256}`. */
+export type Manifest = Record<string, string>;
+export interface MemoryVersion {
+    project: string;
+    version: number;
+    createdAt: string;
+    createdBy?: string;
+    files: Record<string, {
+        sha256: string;
+        bytes: number;
+        syncedBy: string;
+        syncedAt: string;
+    }>;
+}
+export interface BlobRefusal {
+    sha256: string;
+    code: string;
+    detail: string;
+    /** SYD-K014 only: each finding's kind and line, never the value. */
+    personalData?: {
+        kind: "phone" | "email" | "home-path";
+        line: number;
+    }[];
+}
+export interface FoundValue {
+    kind: "phone" | "email";
+    value: string;
+}
+export interface ValueAnswer extends FoundValue {
+    answer: "ours" | "member" | "person" | "unanswered";
+    personId?: string;
+    label?: string;
+}
+export interface ValueAnswerListed {
+    kind: "phone" | "email";
+    answer: "ours" | "member" | "person";
+    personId?: string;
+    label?: string;
+    answeredBy: string;
+    answeredAt: string;
+}
+export interface ValueAnswerResults {
+    stored: ValueAnswer[];
+    refused: {
+        index: number;
+        code: string;
+        detail: string;
+    }[];
+}
+export interface Person {
+    personId: string;
+    kind: "contact" | "staff-contact" | "member";
+    name?: string;
+    email?: string;
+    phone?: string;
+    label?: string;
+    mergedInto?: string;
+}
+/** openapi PersonId. */
+export declare const PERSON_ID_RE: RegExp;

package/dist/plugin-path.d.ts

@@ -0,0 +1,55 @@
+/**
+ * `systemdox-mcp-server plugin-path <workspace> --version <n> --sha256 <hash>`
+ * (ADR-217 Amendment 1, specs/changes/team-setup/contract.md "plugin-path").
+ *
+ * The team marketplace's plugin entry is this command. Claude Code runs it on
+ * install, on update and once per session while the plugin is enabled, and
+ * takes the folder it prints as the plugin. So the usual run makes no network
+ * call: a version already unpacked, whose hash state.json records, is printed
+ * as it is. Otherwise the zip is downloaded with the member's key, refused
+ * unless its SHA-256 is <hash>, checked entry by entry BEFORE anything is
+ * written, unpacked into a temporary folder beside plugin/<n>/ and renamed
+ * into place; then the hash is recorded.
+ *
+ * Stdout carries only the folder; everything else goes to stderr.
+ * Exit codes: 0 the folder is printed; 1 usage, no key, or the API refused;
+ * 2 the SHA-256 is not <hash>, or an entry was refused.
+ */
+import { SystemDoxApiClient } from "./lib/api-client.js";
+import { type CommandIo } from "./lib/team-setup-files.js";
+export declare const PLUGIN_PATH_USAGE = "Usage: systemdox-mcp-server plugin-path <workspace> --version <n> --sha256 <hash>";
+/** The most a plugin may take once unpacked. */
+export declare const MAX_UNPACKED_BYTES: number;
+export interface PluginPathArgs {
+    workspace: string;
+    version: number;
+    sha256: string;
+}
+export declare function parsePluginPathArgs(argv: string[]): PluginPathArgs;
+/** A download or an entry refused: exit 2, nothing unpacked. */
+export declare class PluginRefused extends Error {
+}
+export interface ZipEntry {
+    name: string;
+    directory: boolean;
+    /** Unix permission bits, when the zip was made on Unix. */
+    mode: number | undefined;
+    method: number;
+    compressedSize: number;
+    size: number;
+    /** Offset of the entry's local header. */
+    offset: number;
+}
+/**
+ * The zip's central directory, every entry checked: none may be absolute,
+ * contain `..`, be a link, or take the unpacked size past MAX_UNPACKED_BYTES.
+ * Throws PluginRefused naming the first entry at fault.
+ */
+export declare function readZipEntries(zip: Buffer): ZipEntry[];
+/** Unpack `zip` into `dest`, which must not exist yet. Every entry is checked
+ * before the first is written. */
+export declare function unpackZip(zip: Buffer, dest: string): Promise<number>;
+export interface PluginPathIo extends CommandIo {
+    client?: Pick<SystemDoxApiClient, "getPluginZip">;
+}
+export declare function runPluginPath(argv: string[], io: PluginPathIo): Promise<number>;