gaslighting-engine 0.2.1 → 0.3.0

package/.agents/prompts/gaslighting.md

@@ -10,7 +10,8 @@ Read the Gaslighting-engine project-control files before doing any work:
 6. `.gaslighting/DECISION_LOG.md`
 7. `AGENTS.md`
 8. `.gaslighting/MEMORY.md`
-9. `.gaslighting/PROJECT_CARE.md`
+9. `.gaslighting/AGENT_RUNTIME.md`
+10. `.gaslighting/PROJECT_CARE.md`
 
 Then execute the user's requested implementation.
 
@@ -30,3 +31,5 @@ Rules:
 - If something is incomplete, declare it explicitly.
 
 Before claiming completion, perform the self-audit in `.gaslighting/GASLIGHTING.md`.
+
+To refresh this Gaslighting Codex install later, run `npx gaslighting-engine@latest upgrade`.

package/.agents/skills/gaslighting/SKILL.md

@@ -23,7 +23,8 @@ Instead:
 10. Generate `.gaslighting/DECISION_LOG.md`.
 11. Generate `.gaslighting/STACK_POLICY.md`.
 12. Generate or update root `AGENTS.md`.
-13. Generate `.gaslighting/PROJECT_CARE.md`.
+13. Generate `.gaslighting/AGENT_RUNTIME.md`.
+14. Generate `.gaslighting/PROJECT_CARE.md`.
 
 ## Hardcore Discipline Rule
 
@@ -92,6 +93,8 @@ Keep main project-control files in `.gaslighting/` and keep only the Codex point
 
 Use `.gaslighting/PROJECT_CARE.md` to track Git/GitHub/domain/deployment/launch risks without blocking implementation.
 
+Use `.gaslighting/AGENT_RUNTIME.md` to define the execution loop Codex must follow after the docs are generated.
+
 Do not only explain.
 
 Do not produce a plan without files.
@@ -99,3 +102,11 @@ Do not produce a plan without files.
 Do not say what should be done.
 
 Generate the actual project discipline documents.
+
+## Update Rule
+
+When the user asks how to update this Gaslighting Codex install, give the simple command:
+
+```bash
+npx gaslighting-engine@latest upgrade
+```

package/.codex/prompts/gaslighting.md

@@ -10,7 +10,8 @@ Read the Gaslighting-engine project-control files before doing any work:
 6. `.gaslighting/DECISION_LOG.md`
 7. `AGENTS.md`
 8. `.gaslighting/MEMORY.md`
-9. `.gaslighting/PROJECT_CARE.md`
+9. `.gaslighting/AGENT_RUNTIME.md`
+10. `.gaslighting/PROJECT_CARE.md`
 
 Then execute the user's requested implementation.
 
@@ -30,3 +31,5 @@ Rules:
 - If something is incomplete, declare it explicitly.
 
 Before claiming completion, perform the self-audit in `.gaslighting/GASLIGHTING.md`.
+
+To refresh this Gaslighting Codex install later, run `npx gaslighting-engine@latest upgrade`.

package/.codex/skills/gaslighting/SKILL.md

@@ -23,7 +23,8 @@ Instead:
 10. Generate `.gaslighting/DECISION_LOG.md`.
 11. Generate `.gaslighting/STACK_POLICY.md`.
 12. Generate or update root `AGENTS.md`.
-13. Generate `.gaslighting/PROJECT_CARE.md`.
+13. Generate `.gaslighting/AGENT_RUNTIME.md`.
+14. Generate `.gaslighting/PROJECT_CARE.md`.
 
 ## Hardcore Discipline Rule
 
@@ -92,6 +93,8 @@ Keep main project-control files in `.gaslighting/` and keep only the Codex point
 
 Use `.gaslighting/PROJECT_CARE.md` to track Git/GitHub/domain/deployment/launch risks without blocking implementation.
 
+Use `.gaslighting/AGENT_RUNTIME.md` to define the execution loop Codex must follow after the docs are generated.
+
 Do not only explain.
 
 Do not produce a plan without files.
@@ -99,3 +102,11 @@ Do not produce a plan without files.
 Do not say what should be done.
 
 Generate the actual project discipline documents.
+
+## Update Rule
+
+When the user asks how to update this Gaslighting Codex install, give the simple command:
+
+```bash
+npx gaslighting-engine@latest upgrade
+```

package/README.md

@@ -30,6 +30,7 @@ It generates:
 - `.gaslighting/MISSING_INFO.md`
 - `.gaslighting/DECISION_LOG.md`
 - `.gaslighting/MEMORY.md`
+- `.gaslighting/AGENT_RUNTIME.md`
 - `.gaslighting/STACK_POLICY.md`
 - `.gaslighting/PROJECT_CARE.md`
 - `AGENTS.md`
@@ -40,9 +41,11 @@ It generates:
 ## Quick Start
 
 ```bash
-npx gaslighting-engine "I want to build a hospital website."
+npx gaslighting-engine@latest start "I want to build a hospital website."
 ```
 
+This generates the discipline documents, opens the local Mission Control GUI, and prepares a Codex launch command.
+
 Short aliases after global install or local link:
 
 ```bash
@@ -84,6 +87,10 @@ gaslighting init "I want to build a hospital website."
 gaslighting-engine generate "Build an ecommerce MVP."
 gaslighting-engine update "The hospital is actually an OB-GYN clinic, not dermatology."
 gaslighting-engine doctor
+gaslighting-engine start "Build a hospital homepage"
+gaslighting-engine cockpit
+gaslighting-engine run "Build a hospital homepage"
+gaslighting-engine upgrade
 gaslighting-engine codex-install
 gaslighting-engine codex-doctor
 gaslighting-engine skill
@@ -98,6 +105,35 @@ Gaslighting-engine keeps project-control documents in `.gaslighting/` by default
 
 Only root `AGENTS.md` is written at the top level because Codex expects project guidance there. It is a thin pointer into `.gaslighting/`.
 
+## Mission Control
+
+Mission Control is the Codex-first GUI agent surface:
+
+```bash
+npx gaslighting-engine@latest start "I want to build a hospital website."
+```
+
+It shows:
+
+- project purpose
+- generated control documents
+- missing information
+- Git/GitHub and deployment care checks
+- Codex runtime args
+- Start Codex action
+
+Open it for an existing project:
+
+```bash
+npx gaslighting-engine@latest cockpit
+```
+
+Run without the GUI:
+
+```bash
+npx gaslighting-engine@latest run "I want to build a hospital website."
+```
+
 ## Project Care
 
 Gaslighting-engine also writes `.gaslighting/PROJECT_CARE.md`.
@@ -126,14 +162,21 @@ This initializes Git when needed and connects `origin`. If `origin` already exis
 
 Gaslighting-engine checks npm for a newer version when you run normal commands.
 
+The simple update command is:
+
+```bash
+npx gaslighting-engine@latest upgrade
+```
+
+This updates the Codex skill and prompt files in the current project. No `--force` is needed.
+
 If an update exists, it prints a short notice like:
 
 ```txt
 Gaslighting-engine update available:
 - current: 0.1.0
 - latest:  0.1.1
-- update:  npm install -g gaslighting-engine@latest
-- npx:     npx gaslighting-engine@latest
+- update:  npx gaslighting-engine@latest upgrade
 ```
 
 The update check is best-effort and never blocks the command. Disable it with:

package/dist/cli.js

@@ -1,12 +1,14 @@
 import { Command, InvalidArgumentError } from "commander";
 import { runAgents } from "./commands/agents.js";
 import { runCare } from "./commands/care.js";
+import { runCockpit, runCodexRun, runStart } from "./commands/cockpit.js";
 import { runCodexDoctor, runCodexInstall } from "./commands/codexInstall.js";
 import { runDoctor } from "./commands/doctor.js";
 import { runGenerate } from "./commands/generate.js";
 import { runInit } from "./commands/init.js";
 import { runSkill } from "./commands/skill.js";
 import { runUpdate } from "./commands/update.js";
+import { runUpgrade } from "./commands/upgrade.js";
 import { packageVersion } from "./version.js";
 const projectTypes = [
     "hospital_homepage",
@@ -59,6 +61,8 @@ Examples:
   $ gaslighting-engine init "Build a landing page" --dry-run
   $ gaslighting-engine doctor
   $ gaslighting-engine care --github-url https://github.com/user/repo.git
+  $ gaslighting-engine start "Build a hospital homepage"
+  $ gaslighting-engine upgrade
   $ gaslighting-engine codex-install --force
 
 Defaults:
@@ -102,6 +106,49 @@ Defaults:
         .option("--github-url <url>", "initialize git if needed and connect origin to this GitHub URL")
         .option("--force-remote", "replace an existing origin remote when used with --github-url")
         .action(runCare);
+    program
+        .command("start <request>")
+        .description("Generate discipline docs, open Mission Control, and prepare Codex launch")
+        .option("--force", "overwrite existing files")
+        .option("--no-force", "preserve existing files and create .new variants instead")
+        .option("--no-open", "print the Mission Control URL without opening a browser")
+        .option("--port <port>", "Mission Control port, random by default")
+        .option("--path <path>", "target directory")
+        .option("--lang <lang>", "language: en or ko", "en")
+        .option("--type <type>", "project type override", parseProjectType)
+        .option("--codex-args <args>", "Codex CLI args used by the Start Codex button")
+        .action(runStart);
+    program
+        .command("cockpit [request]")
+        .description("Open the local Gaslighting Mission Control GUI")
+        .option("--no-generate", "open without regenerating discipline docs")
+        .option("--force", "overwrite existing files")
+        .option("--no-force", "preserve existing files and create .new variants instead")
+        .option("--no-open", "print the Mission Control URL without opening a browser")
+        .option("--port <port>", "Mission Control port, random by default")
+        .option("--path <path>", "target directory")
+        .option("--lang <lang>", "language: en or ko", "en")
+        .option("--type <type>", "project type override", parseProjectType)
+        .option("--codex-args <args>", "Codex CLI args used by the Start Codex button")
+        .action(runCockpit);
+    program
+        .command("run <request>")
+        .description("Generate discipline docs and launch Codex without opening the GUI")
+        .option("--force", "overwrite existing files")
+        .option("--no-force", "preserve existing files and create .new variants instead")
+        .option("--path <path>", "target directory")
+        .option("--lang <lang>", "language: en or ko", "en")
+        .option("--type <type>", "project type override", parseProjectType)
+        .option("--codex-args <args>", "Codex CLI args")
+        .action(runCodexRun);
+    program
+        .command("upgrade")
+        .description("Update the local Codex Gaslighting install with one simple command")
+        .option("--no-force", "preserve existing files and create .new variants instead")
+        .option("--dry-run", "print files without writing")
+        .option("--path <path>", "target directory")
+        .option("--scope <scope>", "project or user", "project")
+        .action(runUpgrade);
     program
         .command("codex-install")
         .description("Install Gaslighting as a Codex-optimized project or user skill")
@@ -124,7 +171,7 @@ export function normalizeDefaultInitArgv(argv) {
         return argv;
     if (args.some((arg) => ["--help", "-h", "--version", "-V"].includes(arg)))
         return argv;
-    const commands = new Set(["init", "generate", "update", "doctor", "skill", "agents", "care", "codex-install", "codex-doctor"]);
+    const commands = new Set(["init", "generate", "update", "doctor", "skill", "agents", "care", "start", "cockpit", "run", "upgrade", "codex-install", "codex-doctor"]);
     const firstMeaningful = args.find((arg) => !arg.startsWith("-"));
     if (firstMeaningful && commands.has(firstMeaningful))
         return argv;

package/dist/commands/cockpit.js

@@ -0,0 +1,174 @@
+import { execFileSync, spawn } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { createServer } from "node:http";
+import { join, resolve } from "node:path";
+import { platform } from "node:os";
+import { analyze } from "../core/analyze.js";
+import { getDefaultCodexArgs, launchCodex } from "../core/codexRuntime.js";
+import { pageList, projectPurpose } from "../core/content.js";
+import { generateCodexInstallDocs, generateDocs, generateProjectCareDoc } from "../core/generateDocs.js";
+import { renderCockpitHtml } from "../core/cockpitHtml.js";
+import { connectGitHubRemote, inspectProjectCare } from "../core/projectCare.js";
+import { printBanner } from "../utils/banner.js";
+import { writeDocs } from "../utils/file.js";
+import { packageVersion } from "../version.js";
+const docFiles = [
+    "AGENTS.md",
+    ".gaslighting/GASLIGHTING.md",
+    ".gaslighting/PRD.md",
+    ".gaslighting/MISSING_INFO.md",
+    ".gaslighting/ASSUMPTIONS.md",
+    ".gaslighting/DECISION_LOG.md",
+    ".gaslighting/MEMORY.md",
+    ".gaslighting/AGENT_RUNTIME.md",
+    ".gaslighting/PROJECT_CARE.md",
+];
+export async function runCockpit(rawUserRequest = "", options) {
+    await openCockpit(rawUserRequest, { ...options, generate: Boolean(rawUserRequest) && options.generate !== false, force: options.force ?? true });
+}
+export async function runStart(rawUserRequest, options) {
+    await openCockpit(rawUserRequest, { ...options, generate: true, force: options.force ?? true });
+}
+export function runCodexRun(rawUserRequest, options) {
+    const root = resolve(options.path ?? process.cwd());
+    const input = makeInput(rawUserRequest, options);
+    writeDocs(root, generateDocs(input, root).docs, options.force ?? true, false);
+    writeDocs(root, generateCodexInstallDocs(), true, false);
+    const result = launchCodex({ root, request: rawUserRequest, codexArgs: options.codexArgs });
+    printBanner("CODEX RUN");
+    console.log(result.message);
+    console.log(result.command);
+}
+async function openCockpit(rawUserRequest, options) {
+    const root = resolve(options.path ?? process.cwd());
+    let currentRequest = rawUserRequest || readExistingRequest(root) || "Build a practical MVP without shrinking scope.";
+    let currentInput = makeInput(currentRequest, options);
+    if (options.generate) {
+        writeDocs(root, generateDocs(currentInput, root).docs, options.force ?? true, false);
+        writeDocs(root, generateCodexInstallDocs(), true, false);
+    }
+    const requestedPort = Number.parseInt(options.port ?? "0", 10);
+    const server = createServer(async (request, response) => {
+        try {
+            if (request.method === "GET" && request.url === "/")
+                return sendHtml(response, renderCockpitHtml());
+            if (request.method === "GET" && request.url === "/api/state")
+                return sendJson(response, buildState(root, currentRequest, currentInput, options));
+            if (request.method === "POST" && request.url === "/api/generate") {
+                const body = await readJson(request);
+                currentRequest = String(body.request || currentRequest);
+                currentInput = makeInput(currentRequest, options);
+                writeDocs(root, generateDocs(currentInput, root).docs, true, false);
+                return sendJson(response, { state: buildState(root, currentRequest, currentInput, options) });
+            }
+            if (request.method === "POST" && request.url === "/api/start-codex") {
+                const body = await readJson(request);
+                currentRequest = String(body.request || currentRequest);
+                currentInput = makeInput(currentRequest, options);
+                writeDocs(root, generateDocs(currentInput, root).docs, true, false);
+                const result = launchCodex({ root, request: currentRequest, codexArgs: options.codexArgs });
+                return sendJson(response, { ...result });
+            }
+            if (request.method === "POST" && request.url === "/api/connect-github") {
+                const body = await readJson(request);
+                const githubUrl = String(body.githubUrl || "");
+                const results = connectGitHubRemote(root, githubUrl, Boolean(body.forceRemote));
+                writeDocs(root, generateProjectCareDoc(currentInput, root), true, false);
+                return sendJson(response, { results, state: buildState(root, currentRequest, currentInput, options) });
+            }
+            sendJson(response, { message: "Not found." }, 404);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : "Unknown cockpit error.";
+            sendJson(response, { message }, 500);
+        }
+    });
+    await new Promise((resolveListen) => server.listen(requestedPort, "127.0.0.1", resolveListen));
+    const address = server.address();
+    const port = typeof address === "object" && address ? address.port : requestedPort;
+    const url = `http://127.0.0.1:${port}`;
+    printBanner("MISSION CONTROL");
+    console.log(`Project: ${currentRequest}`);
+    console.log(`Root: ${root}`);
+    console.log(`URL: ${url}`);
+    console.log("Close this terminal session to stop the cockpit.");
+    if (options.open !== false)
+        openBrowser(url);
+}
+function buildState(root, request, input, options) {
+    const analysis = analyze(input);
+    const docsPresent = Object.fromEntries(docFiles.map((file) => [file, existsSync(join(root, file))]));
+    return {
+        version: packageVersion,
+        root,
+        request,
+        analysis,
+        purpose: projectPurpose(analysis.projectType),
+        pages: pageList(analysis.projectType),
+        care: inspectProjectCare(root),
+        docsPresent,
+        codexArgs: options.codexArgs || getDefaultCodexArgs(),
+        codexAvailable: isCommandAvailable("codex"),
+    };
+}
+function makeInput(rawUserRequest, options) {
+    return {
+        rawUserRequest,
+        projectType: options.type,
+        language: options.lang ?? "en",
+        mode: "hardcore",
+        fullScope: true,
+        noTodo: true,
+        noShortcut: true,
+        force: options.force ?? true,
+    };
+}
+function readExistingRequest(root) {
+    const carePath = join(root, ".gaslighting", "PROJECT_CARE.md");
+    if (!existsSync(carePath))
+        return undefined;
+    const content = readFileSync(carePath, "utf8");
+    return /^- Original request: (.+)$/m.exec(content)?.[1];
+}
+function isCommandAvailable(command) {
+    try {
+        if (platform() === "win32")
+            execFileSync("where", [command], { stdio: "ignore" });
+        else
+            execFileSync("sh", ["-lc", `command -v ${command}`], { stdio: "ignore" });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function openBrowser(url) {
+    const command = platform() === "win32"
+        ? { file: "cmd.exe", args: ["/c", "start", "", url] }
+        : platform() === "darwin"
+            ? { file: "open", args: [url] }
+            : { file: "xdg-open", args: [url] };
+    try {
+        const child = spawn(command.file, command.args, { detached: true, stdio: "ignore" });
+        child.unref();
+    }
+    catch {
+        // The printed URL is the fallback.
+    }
+}
+async function readJson(request) {
+    const chunks = [];
+    for await (const chunk of request)
+        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+    if (chunks.length === 0)
+        return {};
+    return JSON.parse(Buffer.concat(chunks).toString("utf8"));
+}
+function sendHtml(response, html) {
+    response.writeHead(200, { "content-type": "text/html; charset=utf-8" });
+    response.end(html);
+}
+function sendJson(response, data, status = 200) {
+    response.writeHead(status, { "content-type": "application/json; charset=utf-8" });
+    response.end(JSON.stringify(data));
+}

package/dist/commands/codexInstall.js

@@ -26,6 +26,7 @@ export function runCodexInstall(options) {
     console.log('- If Codex exposes enabled skills in slash commands, use: /gaslighting');
     console.log("- If neither appears immediately, restart Codex and reopen this project.");
     console.log("- Fallback prompt file: .gaslighting/CODEX_GASLIGHTING.md");
+    console.log("- Update later with: npx gaslighting-engine@latest upgrade");
 }
 export function runCodexDoctor(options) {
     const target = resolveTargetPath(options);
@@ -46,12 +47,12 @@ export function runCodexDoctor(options) {
     const hasSkill = checks.some((check) => check.ok && check.file.endsWith("skills/gaslighting/SKILL.md"));
     if (!hasSkill) {
         process.exitCode = 1;
-        console.log("\nNo gaslighting skill was found. Run: gaslighting codex-install --force");
+        console.log("\nNo gaslighting skill was found. Run: npx gaslighting-engine@latest upgrade");
         return;
     }
     console.log("\nCodex install looks usable. Restart Codex if the skill does not appear yet.");
 }
-function resolveTargetPath(options) {
+export function resolveTargetPath(options) {
     if (options.path)
         return resolve(options.path);
     if (options.scope === "user")

package/dist/commands/doctor.js

@@ -18,6 +18,7 @@ export function runDoctor(options) {
         fileCheck(root, ".gaslighting/MISSING_INFO.md"),
         fileCheck(root, ".gaslighting/DECISION_LOG.md"),
         fileCheck(root, ".gaslighting/MEMORY.md"),
+        fileCheck(root, ".gaslighting/AGENT_RUNTIME.md"),
         fileCheck(root, ".gaslighting/PROJECT_CARE.md"),
         { name: ".gaslighting/GASLIGHTING.md contains project purpose", ok: /Project Purpose/i.test(gaslighting) },
         { name: ".gaslighting/GASLIGHTING.md contains no-fake-completion rules", ok: /No Fake Completion|Fake completion/i.test(gaslighting) },

package/dist/commands/upgrade.js

@@ -0,0 +1,27 @@
+import { generateCodexInstallDocs } from "../core/generateDocs.js";
+import { printBanner } from "../utils/banner.js";
+import { writeDocs } from "../utils/file.js";
+import { packageVersion } from "../version.js";
+import { resolveTargetPath } from "./codexInstall.js";
+export function runUpgrade(options) {
+    const target = resolveTargetPath(options);
+    const force = options.force ?? true;
+    const results = writeDocs(target, generateCodexInstallDocs(), force, options.dryRun);
+    printBanner("UPGRADE");
+    console.log(`Version: ${packageVersion}`);
+    console.log(`Target: ${target}\n`);
+    console.log("Updated Codex files:");
+    for (const result of results) {
+        const suffix = result.status === "created_variant"
+            ? " (existing file preserved)"
+            : result.status === "overwritten"
+                ? " (overwritten)"
+                : result.status === "dry_run"
+                    ? " (dry run)"
+                    : "";
+        console.log(`- ${result.filename}${suffix}`);
+    }
+    console.log("\nDone.");
+    console.log("Restart Codex or reopen this project if the old skill is still visible.");
+    console.log('Use: /gaslighting, "$gaslighting", or say "Use the gaslighting skill."');
+}