gaslighting-engine 0.2.2 → 0.3.1

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.
 

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.

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.
 

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.

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,9 @@ 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
@@ -99,6 +105,49 @@ 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
+
+By default, `Start Codex` closes the local cockpit server and continues Codex in the same terminal that launched Mission Control. This keeps Cursor, Warp, Windows Terminal, or any other terminal flow intact.
+
+If you explicitly want a separate terminal, add:
+
+```bash
+npx gaslighting-engine@latest start "I want to build a hospital website." --new-terminal
+```
+
+To customize Codex flags, use:
+
+```bash
+npx gaslighting-engine@latest start "I want to build a hospital website." --codex-args="--search --dangerously-bypass-approvals-and-sandbox"
+```
+
+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`.

package/dist/cli.js

@@ -1,6 +1,7 @@
 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";
@@ -60,6 +61,7 @@ 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
 
@@ -104,6 +106,44 @@ 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")
+        .option("--new-terminal", "launch Codex in a separate terminal instead of handing off the current terminal")
+        .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")
+        .option("--new-terminal", "launch Codex in a separate terminal instead of handing off the current terminal")
+        .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")
+        .option("--new-terminal", "launch Codex in a separate terminal instead of handing off the current terminal")
+        .action(runCodexRun);
     program
         .command("upgrade")
         .description("Update the local Codex Gaslighting install with one simple command")
@@ -134,7 +174,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", "upgrade", "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,197 @@
+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 { buildCodexCommand, getDefaultCodexArgs, launchCodexInCurrentTerminal, launchCodexInNewTerminal } 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);
+    printBanner("CODEX RUN");
+    console.log(options.newTerminal ? "Starting Codex in a new terminal." : "Handing this terminal over to Codex.");
+    console.log(buildCodexCommand({ root, request: rawUserRequest, codexArgs: options.codexArgs }));
+    const result = options.newTerminal
+        ? launchCodexInNewTerminal({ root, request: rawUserRequest, codexArgs: options.codexArgs })
+        : launchCodexInCurrentTerminal({ root, request: rawUserRequest, codexArgs: options.codexArgs });
+    if (!result.ok)
+        console.log(result.message);
+}
+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);
+                if (options.newTerminal) {
+                    const result = launchCodexInNewTerminal({ root, request: currentRequest, codexArgs: options.codexArgs });
+                    return sendJson(response, { ...result });
+                }
+                const commandPreview = launchMessageForCurrentTerminal(root, currentRequest, options);
+                sendJson(response, commandPreview);
+                setTimeout(() => {
+                    server.close(() => {
+                        console.log("\nMission Control is handing off to Codex in this terminal.\n");
+                        launchCodexInCurrentTerminal({ root, request: currentRequest, codexArgs: options.codexArgs });
+                    });
+                }, 250);
+                return;
+            }
+            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(),
+        launchMode: options.newTerminal ? "new_terminal" : "current_terminal",
+        codexAvailable: isCommandAvailable("codex"),
+    };
+}
+function launchMessageForCurrentTerminal(root, request, options) {
+    return {
+        ok: true,
+        command: buildCodexCommand({ root, request, codexArgs: options.codexArgs }),
+        message: "Mission Control will close and Codex will continue in the same terminal that launched it.",
+    };
+}
+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/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) },