waypoint-codex 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Mark Morgan
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,156 @@
+# Waypoint
+
+It gives a repository a clean working contract for Codex:
+
+- a small `AGENTS.md` map
+- a live `WORKSPACE.md`
+- indexed `docs/`
+- repo-local skills under `.agents/skills/`
+- optional sync for Codex App automations and user-home rules
+
+Waypoint is a standalone Codex-native repository operating system. It is advisory-first, repo-local, and open-source-first.
+
+## Why it exists
+
+The next agent should be able to pick up a repository with full context by reading the repository itself.
+
+Waypoint pushes projects toward:
+
+- docs-first project memory
+- visible operational state
+- explicit session bootstrap
+- battle-tested reusable workflows
+- less hidden magic and less reliance on chat history
+
+## What ships today
+
+- `waypoint init` — scaffold the core repository contract
+- `waypoint doctor` — validate repo health and detect drift
+- `waypoint sync` — rebuild `DOCS_INDEX.md` and optionally sync automations/rules into Codex home
+- `waypoint import-legacy` — analyze a legacy repository layout and write an adoption report into a target Waypoint repo
+
+## Install for development
+
+From the `projects/waypoint/` directory:
+
+```bash
+npm install
+npm run build
+```
+
+Run directly in development:
+
+```bash
+npm run dev -- --help
+```
+
+Run the compiled CLI after building:
+
+```bash
+node dist/src/cli.js --help
+```
+
+Run the tests:
+
+```bash
+npm test
+```
+
+## Install for usage
+
+Global install:
+
+```bash
+npm install -g waypoint-codex
+```
+
+One-off usage:
+
+```bash
+npx waypoint-codex@latest --help
+```
+
+After upgrading the CLI, refresh a repo's scaffold with:
+
+```bash
+waypoint init --with-automations --with-roles
+waypoint doctor
+```
+
+## Quick start
+
+Initialize a repository:
+
+```bash
+npx tsx src/cli.ts init /path/to/repo
+```
+
+Check repo health:
+
+```bash
+npx tsx src/cli.ts doctor /path/to/repo
+```
+
+Sync optional user-home artifacts:
+
+```bash
+npx tsx src/cli.ts sync /path/to/repo
+```
+
+Analyze a legacy repository layout and scaffold a target Waypoint repo:
+
+```bash
+npx tsx src/cli.ts import-legacy /path/to/source-repo /path/to/new-repo --init-target
+```
+
+## Repo contract
+
+Waypoint creates and manages:
+
+```text
+repo/
+├── AGENTS.md
+├── WORKSPACE.md
+├── DOCS_INDEX.md
+├── docs/
+├── .agents/skills/
+└── .waypoint/
+```
+
+Optional packs:
+
+- `.waypoint/automations/*.toml`
+- `.waypoint/rules/*.rules`
+- `.codex/config.toml`
+- `.codex/agents/*.toml`
+
+## Shipped Waypoint skills
+
+- `planning`
+- `error-audit`
+- `observability-audit`
+- `ux-states-audit`
+
+## Optional role pack
+
+If you initialize with `--with-roles`, Waypoint also scaffolds project-scoped Codex role configs for:
+
+- `code-health-reviewer`
+- `code-reviewer`
+- `docs-researcher`
+- `plan-reviewer`
+
+## Tested
+
+- `waypoint init`
+- `waypoint doctor`
+- `waypoint sync` with real Codex automation TOML output
+- `waypoint import-legacy`
+
+## Notes
+
+- Core Waypoint does not require Codex App, Cloud tasks, IDE integration, plugins, or MCP.
+- App automations are supported as an optional declarative sync target.
+- Rules are supported as an optional sync target.
+
+For public docs, see [docs/overview.md](docs/overview.md), [docs/architecture.md](docs/architecture.md), [docs/upgrading.md](docs/upgrading.md), [docs/releasing.md](docs/releasing.md), and [docs/importing-existing-repos.md](docs/importing-existing-repos.md).

package/bin/waypoint.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import "../dist/src/cli.js";
+

package/dist/src/cli.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+import { parseArgs } from "node:util";
+import path from "node:path";
+import process from "node:process";
+import { doctorRepository, importLegacyRepo, initRepository, syncRepository } from "./core.js";
+const VERSION = "0.1.0";
+function resolveRepo(input) {
+    return path.resolve(input ?? ".");
+}
+function printFindings(findings) {
+    if (findings.length === 0) {
+        console.log("Waypoint doctor: no findings.");
+        return;
+    }
+    for (const finding of findings) {
+        console.log(`[${finding.severity.toUpperCase()}] ${finding.category}: ${finding.message}`);
+        console.log(`  Fix: ${finding.remediation}`);
+        for (const filePath of finding.paths ?? []) {
+            console.log(`  Path: ${filePath}`);
+        }
+    }
+}
+function printHelp() {
+    console.log(`usage: waypoint [--version] <command> [options]
+
+Commands:
+  init                Initialize a repository with Waypoint scaffolding
+  doctor              Validate repository health and report drift
+  sync                Rebuild docs index and sync optional user-home artifacts
+  import-legacy       Analyze a legacy repository layout and produce a Waypoint adoption report
+`);
+}
+async function main() {
+    const argv = process.argv.slice(2);
+    if (argv.length === 0 || argv[0] === "-h" || argv[0] === "--help") {
+        printHelp();
+        return 0;
+    }
+    if (argv[0] === "--version") {
+        console.log(VERSION);
+        return 0;
+    }
+    const command = argv[0];
+    if (command === "init") {
+        const { values, positionals } = parseArgs({
+            args: argv.slice(1),
+            options: {
+                "app-friendly": { type: "boolean", default: false },
+                "with-roles": { type: "boolean", default: false },
+                "with-rules": { type: "boolean", default: false },
+                "with-automations": { type: "boolean", default: false }
+            },
+            allowPositionals: true
+        });
+        const projectRoot = resolveRepo(positionals[0]);
+        const results = initRepository(projectRoot, {
+            profile: values["app-friendly"] ? "app-friendly" : "universal",
+            withRoles: values["with-roles"],
+            withRules: values["with-rules"],
+            withAutomations: values["with-automations"]
+        });
+        for (const line of results) {
+            console.log(`- ${line}`);
+        }
+        return 0;
+    }
+    if (command === "doctor") {
+        const { values, positionals } = parseArgs({
+            args: argv.slice(1),
+            options: {
+                json: { type: "boolean", default: false }
+            },
+            allowPositionals: true
+        });
+        const projectRoot = resolveRepo(positionals[0]);
+        const findings = doctorRepository(projectRoot);
+        if (values.json) {
+            console.log(JSON.stringify({ findings }, null, 2));
+        }
+        else {
+            printFindings(findings);
+        }
+        const severities = new Set(findings.map((finding) => finding.severity));
+        if (severities.has("error")) {
+            return 2;
+        }
+        if (severities.has("warn")) {
+            return 1;
+        }
+        return 0;
+    }
+    if (command === "sync") {
+        const { positionals } = parseArgs({
+            args: argv.slice(1),
+            allowPositionals: true
+        });
+        const projectRoot = resolveRepo(positionals[0]);
+        const results = syncRepository(projectRoot);
+        for (const line of results) {
+            console.log(`- ${line}`);
+        }
+        return 0;
+    }
+    if (command === "import-legacy") {
+        const { values, positionals } = parseArgs({
+            args: argv.slice(1),
+            options: {
+                "init-target": { type: "boolean", default: false }
+            },
+            allowPositionals: true
+        });
+        if (positionals.length === 0) {
+            console.error("import-legacy requires a source repository path.");
+            return 2;
+        }
+        const sourceRepo = resolveRepo(positionals[0]);
+        const targetRepo = positionals[1] ? resolveRepo(positionals[1]) : undefined;
+        const result = importLegacyRepo(sourceRepo, targetRepo, {
+            initTarget: values["init-target"]
+        });
+        for (const line of result.actions) {
+            console.log(`- ${line}`);
+        }
+        if (!targetRepo) {
+            console.log(result.report);
+        }
+        return 0;
+    }
+    console.error(`Unknown command: ${command}`);
+    printHelp();
+    return 2;
+}
+main()
+    .then((code) => {
+    process.exitCode = code;
+})
+    .catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+});