@time-machine-lab/tmlbrain 0.1.0

package/scripts/release/parse-auto-release.js

@@ -0,0 +1,166 @@
+#!/usr/bin/env node
+
+const fs = require("fs");
+
+function parseArgs(argv) {
+  const args = {
+    messageFile: null,
+    githubOutput: null,
+    githubEnv: null,
+    json: false,
+  };
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "--message-file") {
+      args.messageFile = argv[++i];
+    } else if (arg === "--github-output") {
+      args.githubOutput = argv[++i];
+    } else if (arg === "--github-env") {
+      args.githubEnv = argv[++i];
+    } else if (arg === "--json") {
+      args.json = true;
+    } else {
+      throw new Error(`Unknown argument: ${arg}`);
+    }
+  }
+
+  return args;
+}
+
+function readStdin() {
+  return fs.readFileSync(0, "utf8");
+}
+
+function findFlagValue(message, flag) {
+  const prefix = `-${flag}:`;
+  const start = message.indexOf(prefix);
+  if (start === -1) {
+    return null;
+  }
+
+  let cursor = start + prefix.length;
+  while (message[cursor] === " " || message[cursor] === "\t") {
+    cursor += 1;
+  }
+
+  const first = message[cursor];
+  if (first === "<") {
+    const end = message.indexOf(">", cursor + 1);
+    if (end === -1) {
+      throw new Error(`Missing closing ">" for -${flag}: value`);
+    }
+    return message.slice(cursor + 1, end).trim();
+  }
+
+  if (first === '"' || first === "'") {
+    const end = message.indexOf(first, cursor + 1);
+    if (end === -1) {
+      throw new Error(`Missing closing quote for -${flag}: value`);
+    }
+    return message.slice(cursor + 1, end).trim();
+  }
+
+  const rest = message.slice(cursor);
+  const match = rest.match(/^[^\s]+/);
+  return match ? match[0].trim() : "";
+}
+
+function parseReleaseMessage(message) {
+  const auto = message.includes("<Auto>");
+  const result = {
+    auto,
+    version: "",
+    runtimePort: "7389",
+    dockerExtraArgs: "",
+  };
+
+  if (!auto) {
+    return result;
+  }
+
+  const version = findFlagValue(message, "v");
+  if (!version) {
+    throw new Error('Auto release commit messages must include "-v:<version>"');
+  }
+
+  const semverPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/;
+  if (!semverPattern.test(version)) {
+    throw new Error(`Invalid -v version "${version}". Expected a Docker-compatible semver value such as 0.1.0`);
+  }
+
+  const runtimePort = findFlagValue(message, "rp") || result.runtimePort;
+  const parsedPort = Number.parseInt(runtimePort, 10);
+  if (!Number.isInteger(parsedPort) || parsedPort < 1 || parsedPort > 65535 || String(parsedPort) !== runtimePort) {
+    throw new Error(`Invalid -rp port "${runtimePort}". Expected an integer from 1 to 65535`);
+  }
+
+  const dockerExtraArgs = findFlagValue(message, "de") || "";
+  if (/[\r\n]/.test(dockerExtraArgs)) {
+    throw new Error("-de value must be a single-line docker runtime argument string");
+  }
+
+  result.version = version;
+  result.runtimePort = runtimePort;
+  result.dockerExtraArgs = dockerExtraArgs;
+  return result;
+}
+
+function appendOutput(file, pairs) {
+  if (!file) {
+    return;
+  }
+
+  const lines = [];
+  for (const [key, value] of Object.entries(pairs)) {
+    lines.push(`${key}=${value}`);
+  }
+  fs.appendFileSync(file, `${lines.join("\n")}\n`);
+}
+
+function appendEnv(file, result) {
+  if (!file) {
+    return;
+  }
+
+  fs.appendFileSync(
+    file,
+    [
+      `TMLBRAIN_RELEASE_VERSION=${result.version}`,
+      `TMLBRAIN_RELEASE_RUNTIME_PORT=${result.runtimePort}`,
+      `TMLBRAIN_RELEASE_DOCKER_EXTRA_ARGS=${result.dockerExtraArgs}`,
+      "",
+    ].join("\n"),
+  );
+}
+
+function main() {
+  const args = parseArgs(process.argv.slice(2));
+  const message = args.messageFile ? fs.readFileSync(args.messageFile, "utf8") : readStdin();
+  const result = parseReleaseMessage(message);
+
+  appendOutput(args.githubOutput, {
+    auto: result.auto ? "true" : "false",
+    version: result.version,
+    runtime_port: result.runtimePort,
+    docker_extra_args: result.dockerExtraArgs,
+  });
+  appendEnv(args.githubEnv, result);
+
+  if (args.json) {
+    process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+  }
+}
+
+if (require.main === module) {
+  try {
+    main();
+  } catch (error) {
+    console.error(error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = {
+  parseReleaseMessage,
+};

package/scripts/sync/.gitkeep

@@ -0,0 +1 @@
+

package/scripts/sync/post-receive.sample

@@ -0,0 +1,8 @@
+#!/usr/bin/env sh
+set -eu
+
+WORKTREE="${TMLBRAIN_WORKTREE:-/srv/tmlbrain-worktree}"
+REPO_DIR="${TMLBRAIN_REPO_DIR:-/srv/tmlbrain.git}"
+
+mkdir -p "$WORKTREE"
+env -u GIT_DIR -u GIT_WORK_TREE git --git-dir="$REPO_DIR" --work-tree="$WORKTREE" checkout -f

package/skills/tmlbrain/SKILL.md

@@ -0,0 +1,192 @@
+---
+name: tmlbrain
+description: Use when an AI agent needs to search, read, update, classify, validate, index, or synchronize the TMLBrain team knowledge base; invoke for TMLBrain knowledge questions, local-first retrieval, server-side knowledge writes, Markdown knowledge edits, conflict-aware updates, and dedicated knowledge repository backup workflows where clients must not operate remote Git repositories directly.
+---
+
+# TMLBrain Skill
+
+Use this skill when an AI agent needs to search, update, classify, or maintain
+the TMLBrain knowledge base.
+
+## Core Principles
+
+- Treat Markdown files under `knowledge/` as the source of truth.
+- Use TMLBrain commands and tools instead of asking normal users to run raw Git commands.
+- Run `tmlbrain capabilities --json` first when the available command surface is unclear.
+- Search local knowledge before answering knowledge-base questions.
+- Prefer exact search first, deterministic metadata/graph indexes second, and LightRAG semantic retrieval when enabled.
+- Clients use read-only local snapshots for search and indexing.
+- Clients MUST NOT push to the server Git repository or dedicated knowledge repository.
+- Add, update, and ingest requests MUST go through the TMLBrain server API with `tmlbrain remote ...` commands.
+- The server is the only runtime that mutates Markdown files, validates them, commits repository changes, and pushes backup state.
+- Ask the server to update the smallest useful Markdown region, usually a front matter field, heading section, block, or link context.
+- Show or summarize server-returned diffs after write requests.
+- Never silently overwrite remote knowledge.
+- Avoid deletion unless the user explicitly asks for it; prefer marking content stale.
+- Normal users do not need to know the internal archive folder/status.
+
+## User-Facing Terms
+
+- When a user says "archive to the knowledge base", "store this", "save this",
+  "record this", or similar, treat it as "save this knowledge into TMLBrain".
+- Use `tmlbrain save` for that user-facing save path. Do not set
+  `status: archived` or choose `knowledge/90-archive/` unless the user
+  explicitly means inactive historical content.
+- Explain available actions as save, search, update, and sync. Avoid exposing
+  internal names such as archive, ingest, Git, commit, or backup unless the user
+  asks about implementation details.
+
+## Knowledge Structure
+
+Use the approved folder taxonomy:
+
+- `knowledge/00-inbox/`: temporary or unclassified notes.
+- `knowledge/10-projects/`: project-specific documents, plans, decisions, and retrospectives.
+- `knowledge/20-areas/`: long-lived responsibility areas.
+- `knowledge/30-resources/`: reusable research, notes, methods, and learning material.
+- `knowledge/40-references/`: stable reference material and checklists.
+- `knowledge/90-archive/`: inactive historical content kept for future search.
+
+Documents outside `00-inbox/` must include:
+
+```yaml
+---
+title: Example
+type: project|area|resource|reference|meeting|decision
+status: draft|active|stale|archived
+owner: TML
+tags: []
+updated: YYYY-MM-DD
+---
+```
+
+Archive reason is optional. A document in `90-archive/` must use
+`status: archived`. This is an internal lifecycle state, not the default place
+for newly saved knowledge.
+
+## Default Workflow
+
+1. Run `tmlbrain capabilities --json` to confirm the installed command surface.
+2. Run `tmlbrain sync --pull` to refresh the local read-only snapshot from the TMLBrain server.
+3. Search with `tmlbrain find "<query>"` or `tmlbrain search "<query>"`.
+4. If needed, use `tmlbrain index` and inspect `.tmlbrain/index/` outputs.
+5. If graph retrieval is enabled, use CocoIndex-derived metadata/graph indexes and LightRAG retrieval after exact search.
+6. Read relevant local source documents.
+7. For new knowledge, use `tmlbrain save`.
+8. For updates, use `tmlbrain remote update --file <path> --replace <old> --with <new>` or a content-file update when a full document replacement is explicitly intended.
+9. Show or summarize the server-returned diff and result.
+10. Run `tmlbrain sync --pull` again so the local snapshot and indexes reflect the accepted server commit.
+
+## Command Recipes
+
+Initialize or repair local runtime:
+
+```text
+npx @time-machine-lab/tmlbrain client install
+```
+
+Run local CLI after global/package installation:
+
+```text
+tmlbrain client install
+```
+
+Enable optional graph runtime:
+
+```text
+tmlbrain graph setup
+```
+
+Validate metadata and links:
+
+```text
+tmlbrain validate
+```
+
+Search exact local Markdown:
+
+```text
+tmlbrain find "keyword"
+```
+
+Rebuild deterministic local index:
+
+```text
+tmlbrain index
+```
+
+Save new knowledge:
+
+```text
+tmlbrain save --title "Title" --content "Content"
+```
+
+Save an existing local file through the server:
+
+```text
+tmlbrain save ./note.md
+```
+
+Update a precise server-side text region:
+
+```text
+tmlbrain remote update --file knowledge/00-inbox/note.md --replace "old text" --with "new text"
+```
+
+Refresh local snapshot from the server:
+
+```text
+tmlbrain sync --pull
+```
+
+Show or change the configured server:
+
+```text
+tmlbrain config show
+tmlbrain config set-server http://server-host:7389 --token <token>
+```
+
+Start the server API from the server worktree:
+
+```text
+tmlbrain serve --host 0.0.0.0 --port 7389
+```
+
+Deploy the server with Docker:
+
+```text
+docker run -d --name tmlbrain-server -p 7389:7389 -e TMLBRAIN_SERVER_TOKEN=<token> -e TMLBRAIN_KNOWLEDGE_REPO=<git-url> -v tmlbrain-data:/data <DOCKER_REPO>:latest
+```
+
+Back up server state:
+
+```text
+tmlbrain backup --dry-run --remote backup
+```
+
+## Conflict Policy
+
+If TMLBrain reports a conflict package:
+
+1. Read the package with `tmlbrain conflict show <id>`.
+2. Summarize the base, local, and remote differences in user-facing language.
+3. Propose a merged Markdown result.
+4. Ask the user to confirm the merged result.
+5. Apply the confirmed merge through `tmlbrain conflict resolve <id> --merged-file <path>`.
+
+Do not ask the user to interpret raw Git conflict markers. Do not force-push or
+silently overwrite remote content.
+
+## Forbidden Client Actions
+
+Do not run these as a normal client workflow:
+
+```text
+tmlbrain sync --push
+git push
+git pull from the server repository
+git push to dedicated knowledge repository backup
+```
+
+If a workflow needs repository mutation, call the TMLBrain server through
+`tmlbrain remote ...` instead.

package/skills/tmlbrain/agents/openai.yaml

@@ -0,0 +1,7 @@
+interface:
+  display_name: "TMLBrain"
+  short_description: "Search, edit, and sync the TMLBrain knowledge base."
+  default_prompt: "Use $tmlbrain to search or update the team knowledge base."
+
+policy:
+  allow_implicit_invocation: true