waypoint-codex 0.1.1 → 0.1.3

package/README.md

@@ -5,9 +5,9 @@ Waypoint is a docs-first repository operating system for Codex.
 It helps the next agent pick up your repo with full context by keeping the important things in markdown files inside the repo:
 
 - `AGENTS.md` for startup instructions
-- `WORKSPACE.md` for live state
+- `.waypoint/WORKSPACE.md` for live state
 - `.waypoint/docs/` for durable project memory
-- `DOCS_INDEX.md` for docs routing
+- `.waypoint/DOCS_INDEX.md` for docs routing
 - repo-local skills for planning and audits
 
 ## Install
@@ -36,10 +36,10 @@ That scaffolds:
 ```text
 repo/
 ├── AGENTS.md
-├── WORKSPACE.md
-├── DOCS_INDEX.md
 ├── .agents/skills/
 └── .waypoint/
+    ├── WORKSPACE.md
+    ├── DOCS_INDEX.md
     ├── docs/
     ├── context/
     └── ...
@@ -49,7 +49,7 @@ repo/
 
 - `waypoint init` — scaffold or refresh the repo
 - `waypoint doctor` — check for drift and missing pieces
-- `waypoint sync` — rebuild `DOCS_INDEX.md` and sync optional automations/rules
+- `waypoint sync` — rebuild `.waypoint/DOCS_INDEX.md` and sync optional automations/rules
 - `waypoint import-legacy` — import from an older repo layout
 
 ## Shipped skills

package/dist/src/cli.js

@@ -1,9 +1,11 @@
 #!/usr/bin/env node
 import { parseArgs } from "node:util";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import path from "node:path";
 import process from "node:process";
 import { doctorRepository, importLegacyRepo, initRepository, syncRepository } from "./core.js";
-const VERSION = "0.1.0";
+const VERSION = JSON.parse(readFileSync(path.resolve(path.dirname(fileURLToPath(import.meta.url)), "../package.json"), "utf8")).version;
 function resolveRepo(input) {
     return path.resolve(input ?? ".");
 }

package/dist/src/core.js

@@ -7,8 +7,8 @@ import { renderDocsIndex } from "./docs-index.js";
 import { readTemplate, renderWaypointConfig, MANAGED_BLOCK_END, MANAGED_BLOCK_START, templatePath } from "./templates.js";
 const DEFAULT_CONFIG_PATH = ".waypoint/config.toml";
 const DEFAULT_DOCS_DIR = ".waypoint/docs";
-const DEFAULT_DOCS_INDEX = "DOCS_INDEX.md";
-const DEFAULT_WORKSPACE = "WORKSPACE.md";
+const DEFAULT_DOCS_INDEX = ".waypoint/DOCS_INDEX.md";
+const DEFAULT_WORKSPACE = ".waypoint/WORKSPACE.md";
 const STATE_DIR = ".waypoint/state";
 const SYNC_RECORDS_FILE = ".waypoint/state/sync-records.json";
 function ensureDir(dirPath) {
@@ -29,6 +29,15 @@ function removePathIfExists(targetPath) {
         rmSync(targetPath, { recursive: true, force: true });
     }
 }
+function migrateLegacyRootFiles(projectRoot) {
+    const legacyWorkspace = path.join(projectRoot, "WORKSPACE.md");
+    const newWorkspace = path.join(projectRoot, DEFAULT_WORKSPACE);
+    if (existsSync(legacyWorkspace) && !existsSync(newWorkspace)) {
+        writeText(newWorkspace, readFileSync(legacyWorkspace, "utf8"));
+    }
+    removePathIfExists(legacyWorkspace);
+    removePathIfExists(path.join(projectRoot, "DOCS_INDEX.md"));
+}
 function appendGitignoreSnippet(projectRoot) {
     const gitignorePath = path.join(projectRoot, ".gitignore");
     const snippet = readTemplate(".gitignore.snippet").trim();
@@ -90,9 +99,12 @@ function scaffoldOptionalCodex(projectRoot) {
 }
 export function initRepository(projectRoot, options) {
     ensureDir(projectRoot);
+    migrateLegacyRootFiles(projectRoot);
     for (const deprecatedPath of [
         "docs/README.md",
         "docs/code-guide.md",
+        "docs/legacy-import",
+        "WAYPOINT_MIGRATION.md",
         ".agents/skills/waypoint-planning",
         ".agents/skills/waypoint-docs",
         ".agents/skills/waypoint-review",
@@ -138,9 +150,9 @@ export function initRepository(projectRoot, options) {
     return [
         "Initialized Waypoint scaffold",
         "Installed managed AGENTS block",
-        "Created WORKSPACE.md and .waypoint/docs/ scaffold",
+        "Created .waypoint/WORKSPACE.md and .waypoint/docs/ scaffold",
         "Installed repo-local Waypoint skills",
-        "Generated DOCS_INDEX.md",
+        "Generated .waypoint/DOCS_INDEX.md",
     ];
 }
 export function loadWaypointConfig(projectRoot) {
@@ -316,7 +328,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "error",
             category: "workspace",
-            message: "WORKSPACE.md is missing.",
+            message: ".waypoint/WORKSPACE.md is missing.",
             remediation: "Run `waypoint init` to scaffold the workspace file.",
             paths: [workspacePath],
         });
@@ -365,7 +377,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "error",
             category: "docs",
-            message: "docs/ directory is missing.",
+            message: ".waypoint/docs/ directory is missing.",
             remediation: "Run `waypoint init` to scaffold docs.",
             paths: [docsDir],
         });
@@ -383,7 +395,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "warn",
             category: "docs",
-            message: "DOCS_INDEX.md is missing.",
+            message: ".waypoint/DOCS_INDEX.md is missing.",
             remediation: "Run `waypoint sync` to generate the docs index.",
             paths: [docsIndexPath],
         });
@@ -392,7 +404,7 @@ export function doctorRepository(projectRoot) {
         findings.push({
             severity: "warn",
             category: "docs",
-            message: "DOCS_INDEX.md is stale.",
+            message: ".waypoint/DOCS_INDEX.md is stale.",
             remediation: "Run `waypoint sync` to rebuild the docs index.",
             paths: [docsIndexPath],
         });
@@ -472,7 +484,7 @@ export function syncRepository(projectRoot) {
     const docsIndexPath = path.join(projectRoot, config.docs_index_file ?? DEFAULT_DOCS_INDEX);
     const docsIndex = renderDocsIndex(projectRoot, docsDir);
     writeText(docsIndexPath, `${docsIndex.content}\n`);
-    const results = ["Rebuilt DOCS_INDEX.md"];
+    const results = ["Rebuilt .waypoint/DOCS_INDEX.md"];
     const featureMap = config.features ?? {};
     if (featureMap.rules) {
         results.push(...syncRules(projectRoot));
@@ -527,7 +539,7 @@ export function importLegacyRepo(sourceRepo, targetRepo, options = {}) {
         }));
     }
     if (targetRepo) {
-        const importDir = path.join(targetRepo, "docs/legacy-import");
+        const importDir = path.join(targetRepo, ".waypoint/docs/legacy-import");
         ensureDir(importDir);
         for (const docName of portableDocs) {
             copyFileSync(path.join(sourceDocsDir, docName), path.join(importDir, docName));
@@ -585,7 +597,7 @@ export function importLegacyRepo(sourceRepo, targetRepo, options = {}) {
         "",
     ].join("\n");
     if (targetRepo) {
-        const reportPath = path.join(targetRepo, "WAYPOINT_MIGRATION.md");
+        const reportPath = path.join(targetRepo, ".waypoint/IMPORT_LEGACY.md");
         writeText(reportPath, report);
         actions.push(`Wrote migration report to ${reportPath}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "waypoint-codex",
-  "version": "0.1.1",
+  "version": "0.1.3",
   "description": "Codex-native repository operating system: scaffolding, docs routing, repo-local skills, doctor, and sync.",
   "license": "MIT",
   "type": "module",

package/templates/.gitignore.snippet

@@ -1,3 +1,4 @@
 # Waypoint state
+.waypoint/DOCS_INDEX.md
 .waypoint/state/
 .waypoint/context/

package/templates/.waypoint/README.md

@@ -3,6 +3,8 @@
 Repo-local Waypoint configuration and optional integration sources.
 
 - `config.toml` — Waypoint feature toggles and file locations
+- `WORKSPACE.md` — live operational state
+- `DOCS_INDEX.md` — generated docs routing map
 - `SOUL.md` — agent identity and working values
 - `agent-operating-manual.md` — required session workflow
 - `docs/` — Waypoint-managed project memory (architecture, decisions, debugging knowledge, durable plans)

package/templates/.waypoint/agent-operating-manual.md

@@ -9,7 +9,7 @@ At the start of every session:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
 3. Read this file
-4. Read `WORKSPACE.md`
+4. Read `.waypoint/WORKSPACE.md`
 5. Read `.waypoint/context/MANIFEST.md`
 6. Read every file listed in that manifest
 
@@ -19,7 +19,7 @@ Do not skip this sequence.
 
 The repository should contain the context the next agent needs.
 
-- `WORKSPACE.md` is the live operational record: in progress, current state, next steps
+- `.waypoint/WORKSPACE.md` is the live operational record: in progress, current state, next steps
 - `.waypoint/docs/` is the durable project memory: architecture, decisions, integration notes, debugging knowledge, and durable plans
 - `.waypoint/context/` is the generated session context bundle: current git/PR/doc index state
 
@@ -29,9 +29,9 @@ If something important lives only in your head or in the chat transcript, the re
 
 - Read code before editing it.
 - Follow the repo's documented patterns when they are healthy.
-- Update `WORKSPACE.md` as live execution state when progress meaningfully changes.
+- Update `.waypoint/WORKSPACE.md` as live execution state when progress meaningfully changes.
 - Update `.waypoint/docs/` when durable knowledge changes.
-- Rebuild `DOCS_INDEX.md` whenever routable docs change.
+- Rebuild `.waypoint/DOCS_INDEX.md` whenever routable docs change.
 - Use the repo-local skills and optional reviewer agents instead of improvising from scratch.
 
 ## Documentation expectations

package/templates/.waypoint/config.toml

@@ -1,8 +1,8 @@
 version = 1
 profile = "__PROFILE__"
-workspace_file = "WORKSPACE.md"
+workspace_file = ".waypoint/WORKSPACE.md"
 docs_dir = ".waypoint/docs"
-docs_index_file = "DOCS_INDEX.md"
+docs_index_file = ".waypoint/DOCS_INDEX.md"
 
 [features]
 repo_skills = true

package/templates/.waypoint/scripts/build-docs-index.mjs

@@ -139,7 +139,7 @@ export function renderDocsIndex(projectRoot) {
 }
 
 export function writeDocsIndex(projectRoot) {
-  const outputPath = path.join(projectRoot, "DOCS_INDEX.md");
+  const outputPath = path.join(projectRoot, ".waypoint", "DOCS_INDEX.md");
   writeFileSync(outputPath, renderDocsIndex(projectRoot), "utf8");
   return outputPath;
 }

package/templates/.waypoint/scripts/prepare-context.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 
-import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, readdirSync, realpathSync, statSync, writeFileSync } from "node:fs";
 import { execSync } from "node:child_process";
 import os from "node:os";
 import path from "node:path";
@@ -35,6 +35,232 @@ function safeExec(command, cwd) {
   }
 }
 
+const SESSION_DIR_NAMES = ["sessions", "archived_sessions"];
+const SECRET_PATTERNS = [
+  /npm_[A-Za-z0-9]+/g,
+  /github_pat_[A-Za-z0-9_]+/g,
+  /gh[pousr]_[A-Za-z0-9]+/g,
+  /sk-[A-Za-z0-9]+/g,
+  /sk_[A-Za-z0-9]+/g,
+  /fc-[A-Za-z0-9]+/g,
+  /AIza[0-9A-Za-z\-_]{20,}/g,
+];
+const MAX_RECENT_TURNS = 25;
+
+function codexHome() {
+  return process.env.CODEX_HOME || path.join(os.homedir(), ".codex");
+}
+
+function redactSecrets(text) {
+  return SECRET_PATTERNS.reduce((current, pattern) => current.replace(pattern, "[REDACTED]"), text);
+}
+
+function isWithinPath(childPath, parentPath) {
+  const rel = path.relative(realpathSync(parentPath), realpathSync(childPath));
+  return rel === "" || (!rel.startsWith("..") && !path.isAbsolute(rel));
+}
+
+function collectSessionFiles(rootDir) {
+  const files = [];
+
+  function walk(currentDir) {
+    if (!existsSync(currentDir)) {
+      return;
+    }
+    for (const entry of readdirSync(currentDir)) {
+      const fullPath = path.join(currentDir, entry);
+      let stats;
+      try {
+        stats = statSync(fullPath);
+      } catch {
+        continue;
+      }
+      if (stats.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.endsWith(".jsonl")) {
+        files.push(fullPath);
+      }
+    }
+  }
+
+  walk(rootDir);
+  return files;
+}
+
+function extractMessageText(content) {
+  if (!Array.isArray(content)) {
+    return "";
+  }
+  return content
+    .filter((block) => block?.type === "input_text" || block?.type === "output_text")
+    .map((block) => (typeof block?.text === "string" ? block.text : ""))
+    .join("")
+    .trim();
+}
+
+function isBootstrapNoise(role, text) {
+  return role === "user" && text.startsWith("# AGENTS.md instructions for ");
+}
+
+function mergeConsecutiveTurns(turns) {
+  const merged = [];
+  for (const turn of turns) {
+    const previous = merged.at(-1);
+    if (previous && previous.role === turn.role) {
+      if (previous.text !== turn.text) {
+        previous.text = `${previous.text}\n\n${turn.text}`;
+      }
+      previous.timestamp = turn.timestamp || previous.timestamp;
+      previous.messageCount += 1;
+      continue;
+    }
+    merged.push({ ...turn });
+  }
+  return merged;
+}
+
+function parseSession(sessionFile, projectRoot) {
+  let sessionCwd = null;
+  let compactionCount = 0;
+  const rawTurns = [];
+  const compactionBoundaries = [];
+
+  for (const line of readFileSync(sessionFile, "utf8").split("\n")) {
+    if (!line.trim()) {
+      continue;
+    }
+
+    let parsed;
+    try {
+      parsed = JSON.parse(line);
+    } catch {
+      continue;
+    }
+
+    if (parsed.type === "session_meta") {
+      const cwd = parsed.payload?.cwd;
+      if (typeof cwd === "string") {
+        sessionCwd = cwd;
+      }
+      continue;
+    }
+
+    if (parsed.type === "compacted") {
+      compactionCount += 1;
+      compactionBoundaries.push(rawTurns.length);
+      continue;
+    }
+
+    if (parsed.type !== "response_item" || parsed.payload?.type !== "message") {
+      continue;
+    }
+
+    const role = parsed.payload?.role;
+    if (role !== "user" && role !== "assistant") {
+      continue;
+    }
+
+    const text = redactSecrets(extractMessageText(parsed.payload?.content));
+    if (!text || isBootstrapNoise(role, text)) {
+      continue;
+    }
+
+    rawTurns.push({
+      role,
+      text,
+      timestamp: parsed.timestamp || null,
+      messageCount: 1,
+    });
+  }
+
+  if (!sessionCwd || !isWithinPath(sessionCwd, projectRoot)) {
+    return null;
+  }
+
+  const selectedFromPreCompaction = compactionBoundaries.length > 0;
+  const relevantTurns = selectedFromPreCompaction ? rawTurns.slice(0, compactionBoundaries.at(-1)) : rawTurns;
+  const turns = mergeConsecutiveTurns(relevantTurns);
+  if (turns.length === 0) {
+    return null;
+  }
+
+  return {
+    path: sessionFile,
+    sessionCwd,
+    turns,
+    compactionCount,
+    selectedFromPreCompaction,
+  };
+}
+
+function latestMatchingSession(projectRoot) {
+  const matches = [];
+  for (const dirName of SESSION_DIR_NAMES) {
+    for (const sessionFile of collectSessionFiles(path.join(codexHome(), dirName))) {
+      const parsed = parseSession(sessionFile, projectRoot);
+      if (parsed) {
+        matches.push(parsed);
+      }
+    }
+  }
+
+  matches.sort((a, b) => statSync(b.path).mtimeMs - statSync(a.path).mtimeMs);
+  return matches[0] || null;
+}
+
+function writeRecentThread(contextDir, projectRoot) {
+  const filePath = path.join(contextDir, "RECENT_THREAD.md");
+  const snapshot = latestMatchingSession(projectRoot);
+  const generatedAt = new Date().toString();
+
+  if (!snapshot) {
+    writeFileSync(
+      filePath,
+      [
+        "# Recent Thread",
+        "",
+        `Generated by \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\` on ${generatedAt}.`,
+        "",
+        "No matching local Codex session was found for this repo yet.",
+        "",
+      ].join("\n"),
+      "utf8"
+    );
+    return filePath;
+  }
+
+  const selectedTurns = snapshot.turns.slice(-MAX_RECENT_TURNS);
+  const relSessionPath = path.relative(codexHome(), snapshot.path);
+  const lines = [
+    "# Recent Thread",
+    "",
+    `Generated by \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\` on ${generatedAt}.`,
+    "",
+    `- Source session: \`${relSessionPath}\``,
+    `- Session cwd: \`${snapshot.sessionCwd}\``,
+    `- Included turns: ${selectedTurns.length} of ${snapshot.turns.length} meaningful turns`,
+    `- Compactions in source session: ${snapshot.compactionCount}`,
+    snapshot.selectedFromPreCompaction
+      ? "- Selection rule: take the 25 meaningful turns immediately before the last compaction."
+      : "- Selection rule: no compaction found, so take the latest meaningful turns from the local transcript.",
+    "- Noise filter: bootstrap AGENTS payloads are excluded.",
+    "- Secret handling: obvious token formats are redacted before writing this file.",
+    "",
+  ];
+
+  selectedTurns.forEach((turn, index) => {
+    const mergedSuffix = turn.messageCount > 1 ? ` (merged ${turn.messageCount} messages)` : "";
+    const timestamp = turn.timestamp ? ` - ${turn.timestamp}` : "";
+    lines.push(`## ${index + 1}. ${turn.role[0].toUpperCase()}${turn.role.slice(1)}${mergedSuffix}${timestamp}`);
+    lines.push("");
+    lines.push(turn.text);
+    lines.push("");
+  });
+
+  writeFileSync(filePath, `${lines.join("\n").trimEnd()}\n`, "utf8");
+  return filePath;
+}
+
 function collectNestedGitRepos(projectRoot) {
   const repos = [];
 
@@ -140,6 +366,7 @@ function main() {
       "```",
     ].join("\n")
   );
+  const recentThreadPath = writeRecentThread(contextDir, projectRoot);
 
   const manifestPath = path.join(contextDir, "MANIFEST.md");
   const manifestLines = [
@@ -154,13 +381,14 @@ function main() {
     `- \`${path.relative(projectRoot, recentCommitsPath)}\` — recent commits`,
     `- \`${path.relative(projectRoot, nestedReposPath)}\` — recent commits in nested repositories`,
     `- \`${path.relative(projectRoot, prsPath)}\` — open and recently merged pull requests`,
+    `- \`${path.relative(projectRoot, recentThreadPath)}\` — latest meaningful turns from the local Codex session for this repo`,
     `- \`${path.relative(projectRoot, docsIndexPath)}\` — current docs index`,
     "",
     "## Stable source-of-truth files to read before this manifest",
     "",
     "- `.waypoint/SOUL.md`",
     "- `.waypoint/agent-operating-manual.md`",
-    "- `WORKSPACE.md`",
+    "- `.waypoint/WORKSPACE.md`",
     "",
     `Generated by: \`${path.relative(projectRoot, fileURLToPath(import.meta.url))}\``,
     "",
@@ -171,4 +399,3 @@ function main() {
 }
 
 main();
-

package/templates/managed-agents-block.md

@@ -7,14 +7,14 @@ Before doing substantial work:
 1. Run `node .waypoint/scripts/prepare-context.mjs`
 2. Read `.waypoint/SOUL.md`
 3. Read `.waypoint/agent-operating-manual.md`
-4. Read `WORKSPACE.md`
+4. Read `.waypoint/WORKSPACE.md`
 5. Read `.waypoint/context/MANIFEST.md`
 6. Read every file listed in the manifest
 
 This is mandatory, not optional. Do not skip the context refresh or skip files in the manifest.
 
 Working rules:
-- Keep `WORKSPACE.md` current as the live execution state
+- Keep `.waypoint/WORKSPACE.md` current as the live execution state
 - Update `.waypoint/docs/` when behavior or durable project knowledge changes
 - Use the repo-local skills Waypoint ships for structured workflows when relevant
 - Treat the generated context bundle as required session bootstrap, not optional reference material