portable-agent-layer 0.14.1 → 0.15.0

package/assets/skills/telos/SKILL.md

@@ -29,12 +29,24 @@ Read the file directly from `~/.agents/PAL/telos/` when the user asks about any
 
 ## Updating
 
-Use the update tool for all changes. It validates the file, creates a backup, appends content, and logs the change:
+### General TELOS files (append)
+
+For all files except PROJECTS.md — appends content, creates backup, logs the change:
 
 ```bash
 bun ~/.agents/skills/telos/tools/update-telos.ts <FILE> "<content>" "<description>"
 ```
 
+### Projects (upsert by ID)
+
+For PROJECTS.md — upserts a row by the ID column. Replaces if the ID exists, appends if new:
+
+```bash
+bun ~/.agents/skills/telos/tools/update-projects.ts <id> "<row>" "<description>"
+```
+
+The ID is the first column of the table. Use short, lowercase, kebab-case slugs (e.g., `my-project`, `side-gig`).
+
 ## Routing
 
 | Intent | Action |
@@ -66,15 +78,24 @@ User: "add my new side project"
 → Ask: "What's the project name, status, and priority?"
 → User provides details
 → Show the row you'll add, confirm
-→ Run: bun ~/.agents/skills/telos/tools/update-telos.ts PROJECTS.md "| Side Project | In progress | Medium | Description |" "Added Side Project"
+→ Run: bun ~/.agents/skills/telos/tools/update-projects.ts side-project "| side-project | Side Project | In progress | Medium | Description |" "Added Side Project"
+```
+
+**Example 3: Updating a project**
+```
+User: "mark X as complete"
+→ Read PROJECTS.md, find the entry and its ID
+→ Show updated row, confirm
+→ Run: bun ~/.agents/skills/telos/tools/update-projects.ts some-id "| some-id | Project Name | Complete | High | ... |" "Marked project as complete"
+→ The existing row is replaced, not duplicated
 ```
 
-**Example 3: Updating goals**
+**Example 4: Updating goals**
 ```
 User: "I finished the migration, update my goals"
 → Read GOALS.md to see current state
 → Discuss what changed — what's done, what's next
-→ Run tool to append updated goals
+→ Run tool with --id to update existing goal entry
 → Remind: CLAUDE.md regenerates next session
 ```
 

package/assets/skills/telos/tools/update-projects.ts

@@ -0,0 +1,101 @@
+#!/usr/bin/env bun
+/**
+ * UpdateProjects — Upsert a project row in PROJECTS.md by ID.
+ *
+ * Usage:
+ *   bun update-projects.ts <id> "<row>" "<description>"
+ *
+ * - <id> is the value in the first column (e.g., "my-proj", "side-gig")
+ * - <row> is the full table row including the ID column (e.g., "| my-proj | My Project | Done | High | ... |")
+ * - If a row with that ID exists, it is replaced
+ * - If no row with that ID exists, it is appended
+ * - Creates a timestamped backup before modifying
+ * - Logs the change to updates.md
+ */
+
+import {
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  readFileSync,
+  writeFileSync,
+} from "node:fs";
+import { resolve } from "node:path";
+import { palHome } from "../../../../src/hooks/lib/paths";
+
+const TELOS_DIR = resolve(palHome(), "telos");
+const BACKUPS_DIR = resolve(TELOS_DIR, "backups");
+const UPDATES_LOG = resolve(TELOS_DIR, "updates.md");
+const PROJECTS_FILE = resolve(TELOS_DIR, "PROJECTS.md");
+
+function timestamp(): string {
+  const now = new Date();
+  const pad = (n: number) => n.toString().padStart(2, "0");
+  return `${now.getFullYear()}${pad(now.getMonth() + 1)}${pad(now.getDate())}-${pad(now.getHours())}${pad(now.getMinutes())}${pad(now.getSeconds())}`;
+}
+
+function isoDate(): string {
+  return new Date().toISOString().replace("T", " ").slice(0, 19);
+}
+
+const args = process.argv.slice(2);
+const id = args[0];
+const row = args[1];
+const description = args[2];
+
+if (!id || !row || !description) {
+  console.error('Usage: bun update-projects.ts <id> "<row>" "<description>"');
+  console.error(
+    '\nExample: bun update-projects.ts my-proj "| my-proj | My Project | In progress | High | Notes |" "Added My Project"'
+  );
+  process.exit(1);
+}
+
+// Backup
+mkdirSync(BACKUPS_DIR, { recursive: true });
+if (existsSync(PROJECTS_FILE)) {
+  const backupName = `PROJECTS-${timestamp()}.md`;
+  copyFileSync(PROJECTS_FILE, resolve(BACKUPS_DIR, backupName));
+}
+
+const existing = existsSync(PROJECTS_FILE) ? readFileSync(PROJECTS_FILE, "utf-8") : "";
+
+const escapedId = id.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+const idPattern = new RegExp(`^\\|\\s*${escapedId}\\s*\\|.*$`, "m");
+let mode: "replaced" | "appended";
+
+if (idPattern.test(existing)) {
+  const updated = existing.replace(idPattern, row.trim());
+  writeFileSync(PROJECTS_FILE, updated, "utf-8");
+  mode = "replaced";
+} else {
+  const separator = existing.trim() ? "\n" : "";
+  writeFileSync(
+    PROJECTS_FILE,
+    `${existing.trimEnd()}${separator}${row.trim()}\n`,
+    "utf-8"
+  );
+  mode = "appended";
+}
+
+// Log change
+const logEntry = `- **${isoDate()}** — \`PROJECTS.md\` [${id}]: ${description}`;
+const existingLog = existsSync(UPDATES_LOG)
+  ? readFileSync(UPDATES_LOG, "utf-8")
+  : "# TELOS Updates\n";
+writeFileSync(UPDATES_LOG, `${existingLog.trimEnd()}\n${logEntry}\n`, "utf-8");
+
+console.log(
+  JSON.stringify(
+    {
+      file: "PROJECTS.md",
+      id,
+      mode,
+      backed_up: true,
+      logged: true,
+      description,
+    },
+    null,
+    2
+  )
+);

package/assets/skills/telos/tools/update-telos.ts

@@ -1,6 +1,6 @@
 #!/usr/bin/env bun
 /**
- * UpdateTelos — Validate, backup, update, and log changes to TELOS files.
+ * UpdateTelos — Validate, backup, append, and log changes to TELOS files.
  *
  * Usage:
  *   bun update-telos.ts <file> "<content>" "<description>"
@@ -9,6 +9,8 @@
  * - Creates a timestamped backup before modifying
  * - Appends content (preserves existing)
  * - Logs the change to updates.md
+ *
+ * For PROJECTS.md upserts (add/update by ID), use update-projects.ts instead.
  */
 
 import {
@@ -34,7 +36,6 @@ const VALID_FILES = [
   "MISSION.md",
   "MODELS.md",
   "NARRATIVES.md",
-  "PROJECTS.md",
   "STRATEGIES.md",
 ];
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "portable-agent-layer",
-  "version": "0.14.1",
+  "version": "0.15.0",
   "description": "PAL — Portable Agent Layer: persistent personal context for AI coding assistants",
   "type": "module",
   "bin": {