create-chat-gpt-repo-memory 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026
+
+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,275 @@
+# create-chat-gpt-repo-memory
+
+`create-chat-gpt-repo-memory` scaffolds Git-tracked repo memory files for ChatGPT and Codex-style coding workflows.
+
+It creates a root `AGENTS.md` instruction file plus a shared `.agent-memory/` folder containing durable project memory templates. The package scaffolds structure and template content only. It does not analyze the target repository.
+
+## Quickstart
+
+### Step 1 — scaffold the files
+
+Run this inside any repository:
+
+```bash
+npx create-chat-gpt-repo-memory
+```
+
+This creates `AGENTS.md` and an `.agent-memory/` directory with template memory files, and updates `.gitignore` to exclude local agent cache files.
+
+### Step 2 — let ChatGPT fill them in
+
+Open a ChatGPT session with access to your repository and run:
+
+```
+Use AGENTS.md as your operating instructions for this repository. Then read .agent-memory/prompts/fill-project-map.md and execute it. Fill or update the .agent-memory files using only verified repository facts. Do not include secrets.
+```
+
+ChatGPT will inspect your repository and populate the memory files with your actual stack, architecture, conventions, entry points, workflows, and more.
+
+### Step 3 — commit
+
+```bash
+git add AGENTS.md .agent-memory/ .gitignore
+git commit -m "Add ChatGPT repo memory"
+```
+
+Done. Every future session that reads `AGENTS.md` and `.agent-memory/` will have full project context before doing anything else.
+
+## Why `AGENTS.md` Instead of `CHATGPT.md`
+
+This package uses `AGENTS.md` because that is the Codex-style repository instruction convention.
+
+That keeps one shared instruction surface for mixed workflows:
+
+- Codex-style agents can start from `AGENTS.md`
+- ChatGPT Projects can upload or reference the same files
+- Teams can track one repo-memory structure in Git
+
+This package does not generate `CHATGPT.md`.
+
+## Why `.agent-memory/` Instead of `.chatgpt/`
+
+This package uses `.agent-memory/` as shared Git-tracked project memory:
+
+- readable by humans and coding agents
+- easy to version in Git
+- neutral naming that works across tools
+- separate from local cache artifacts
+
+This package does not generate `.chatgpt/`.
+
+## Installation
+
+Use with `npx`:
+
+```bash
+npx create-chat-gpt-repo-memory
+```
+
+Or install globally:
+
+```bash
+npm install -g create-chat-gpt-repo-memory
+create-chat-gpt-repo-memory
+```
+
+## Usage
+
+```bash
+npx create-chat-gpt-repo-memory
+npx create-chat-gpt-repo-memory --template dotnet
+npx create-chat-gpt-repo-memory --force
+npx create-chat-gpt-repo-memory --no-gitignore
+npx create-chat-gpt-repo-memory --cwd ../some-project
+```
+
+## Options
+
+- `--force`: overwrite existing generated files
+- `--no-gitignore`: skip `.gitignore` updates
+- `--template <name>`: choose `generic` or `dotnet`
+- `--cwd <path>`: target directory to scaffold into
+
+## Files Generated
+
+```text
+AGENTS.md
+.agent-memory/project-map.md
+.agent-memory/architecture.md
+.agent-memory/conventions.md
+.agent-memory/workflows.md
+.agent-memory/update-project-map.md
+.agent-memory/prompts/fill-project-map.md
+.agent-memory/prompts/start-session.md
+```
+
+The package does not create `.agent-memory-local/`. That path is added to `.gitignore` only.
+
+## Template Options
+
+- `generic`: baseline repository memory template
+- `dotnet`: generic template plus .NET-specific guidance
+
+Template variables:
+
+- `{{PROJECT_NAME}}`
+- `{{TEMPLATE_NAME}}`
+- `{{GENERATED_BY}}`
+
+## Initial Map-Fill Prompt
+
+```text
+Use AGENTS.md as your operating instructions for this repository. Then read .agent-memory/prompts/fill-project-map.md and execute it. Fill or update the .agent-memory files using only verified repository facts. Do not include secrets.
+```
+
+## Future Session-Start Prompt
+
+```text
+Use AGENTS.md as your operating instructions, then read .agent-memory/prompts/start-session.md and follow it for this task.
+```
+
+## Overwrite Safety
+
+The CLI never silently overwrites generated files.
+
+- If a file does not exist, it is created.
+- If a file exists and `--force` is not set, it is skipped by default.
+- If a file exists and `--force` is set, it is overwritten.
+
+For an existing `AGENTS.md`, the CLI is more careful:
+
+- If the file does not already contain repo-memory guidance, the CLI appends a managed repo-memory instructions block instead of replacing the whole file.
+- If that managed block already exists, the CLI updates just that block on later runs.
+- If the existing `AGENTS.md` already contains its own repo-memory guidance and the CLI cannot safely merge it, the CLI asks whether to skip or overwrite when running interactively.
+- In a non-interactive environment, that unmergeable case falls back to skip.
+
+## `.gitignore` Behavior
+
+Unless `--no-gitignore` is used, the CLI updates or creates `.gitignore` and adds this local-only block when needed:
+
+```gitignore
+# Local agent memory/cache
+.agent-memory-local/
+.agent-memory/**/*.db
+.agent-memory/**/*.sqlite
+.agent-memory/**/*.sqlite3
+.agent-memory/**/*.log
+```
+
+The update is idempotent. If `.gitignore` already contains `.agent-memory-local/`, the block is not appended again.
+
+The package also removes legacy `.chatgpt-local/` and `.chatgpt/**/*.(db|sqlite|sqlite3|log)` ignore lines when it updates `.gitignore`.
+
+The Git-tracked memory files themselves are never ignored by this package.
+
+## Notes for Codex-Style Usage
+
+- `AGENTS.md` is the root instruction file.
+- Codex-style agents should start from the repo root so `AGENTS.md` can be discovered.
+- Keep `.agent-memory/project-map.md` concise and move detail into supporting memory files.
+
+## Notes for ChatGPT Project Usage
+
+- ChatGPT Projects do not automatically treat `.agent-memory/` as a magic folder.
+- Add `AGENTS.md` and `.agent-memory/` files to the project, or make sure they are available in repository context.
+- Start future sessions by telling ChatGPT to read `AGENTS.md` and the relevant `.agent-memory/` files.
+
+## Publishing
+
+```bash
+npm login
+npm publish --access public
+```
+
+## Local Testing
+
+```bash
+npm link
+create-chat-gpt-repo-memory --cwd ../some-test-repo
+```
+
+## Manual Test Plan
+
+Create a temporary test project:
+
+```bash
+mkdir /tmp/chatgpt-memory-test
+cd /tmp/chatgpt-memory-test
+node /path/to/create-chat-gpt-repo-memory/bin/cli.js
+```
+
+Verify:
+
+```text
+AGENTS.md exists
+.agent-memory/project-map.md exists
+.agent-memory/architecture.md exists
+.agent-memory/conventions.md exists
+.agent-memory/workflows.md exists
+.agent-memory/update-project-map.md exists
+.agent-memory/prompts/fill-project-map.md exists
+.agent-memory/prompts/start-session.md exists
+.gitignore contains Local agent memory/cache block
+```
+
+Run it again without `--force`.
+
+Expected:
+
+```text
+files are skipped
+.gitignore is unchanged
+no duplicate gitignore block
+```
+
+Run with `--force`.
+
+Expected:
+
+```text
+existing generated files are overwritten
+.gitignore remains unchanged
+```
+
+Run with dotnet template:
+
+```bash
+mkdir /tmp/chatgpt-memory-dotnet-test
+node /path/to/create-chat-gpt-repo-memory/bin/cli.js --template dotnet --cwd /tmp/chatgpt-memory-dotnet-test
+```
+
+Expected:
+
+```text
+dotnet-specific sections are present
+.agent-memory/prompts/start-session.md exists
+```
+
+Run against an invalid template:
+
+```bash
+node /path/to/create-chat-gpt-repo-memory/bin/cli.js --template invalid
+```
+
+Expected:
+
+```text
+clear unsupported-template error
+exit code 1
+```
+
+Search for stale terms:
+
+```bash
+grep -R "CHATGPT.md\|\.chatgpt\|CLAUDE.md\|\.claude\|create-claude" .
+```
+
+Expected:
+
+```text
+No stale references, except intentional README explanation if present.
+```
+
+## License
+
+MIT

package/bin/cli.js

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+
+import { Command } from "commander";
+import { resolveTargetDirectory } from "../src/paths.js";
+import { initChatGptRepoMemory } from "../src/init.js";
+import { SUPPORTED_TEMPLATES } from "../src/templateResolver.js";
+
+const program = new Command();
+
+program
+  .name("create-chat-gpt-repo-memory")
+  .description("Scaffold Git-tracked repo memory files for ChatGPT and Codex-style coding workflows.")
+  .version("0.1.0");
+
+function addOptions(cmd) {
+  return cmd
+    .option("--force", "Overwrite existing generated files.", false)
+    .option("--no-gitignore", "Do not update .gitignore.")
+    .option("--template <name>", `Template to use. Supported values: ${SUPPORTED_TEMPLATES.join(", ")}.`, "generic")
+    .option("--cwd <path>", "Directory where files should be created.", process.cwd());
+}
+
+async function runInit(options) {
+  const { force, gitignore: updateGitignore, template, cwd } = options;
+
+  let rootDir;
+  try {
+    rootDir = await resolveTargetDirectory(cwd);
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  let result;
+  try {
+    result = await initChatGptRepoMemory({ rootDir, force, updateGitignore, template });
+  } catch (err) {
+    console.error(`Error: ${err.message}`);
+    process.exit(1);
+  }
+
+  const { created, overwritten, skipped, gitignoreStatus } = result;
+
+  console.log("\nChatGPT/Codex repo memory initialized.\n");
+
+  if (created.length > 0) {
+    console.log("Created:");
+    for (const f of created) console.log(`  - ${f}`);
+    console.log();
+  }
+
+  if (overwritten.length > 0) {
+    console.log("Overwritten:");
+    for (const f of overwritten) console.log(`  - ${f}`);
+    console.log();
+  }
+
+  if (skipped.length > 0) {
+    console.log("Skipped:");
+    for (const f of skipped) console.log(`  - ${f}`);
+    console.log();
+  }
+
+  console.log(`Gitignore: ${gitignoreStatus}\n`);
+
+  console.log("Next steps:");
+  console.log("  1. Commit AGENTS.md and .agent-memory/ files.");
+  console.log("  2. For Codex-style agents, start from the repo root so the agent can read AGENTS.md.");
+  console.log("  3. For ChatGPT Projects, add AGENTS.md and .agent-memory/ as project files or make sure they are available in the repository context.");
+  console.log('  4. Kick off the initial map fill with:');
+  console.log('     "Use AGENTS.md as your operating instructions for this repository. Then read .agent-memory/prompts/fill-project-map.md and execute it. Fill or update the .agent-memory files using only verified repository facts. Do not include secrets."');
+  console.log();
+}
+
+addOptions(program);
+
+program.action(async () => {
+  await runInit(program.opts());
+});
+
+program.parseAsync(process.argv).catch((err) => {
+  console.error(`Error: ${err.message}`);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "create-chat-gpt-repo-memory",
+  "version": "0.1.0",
+  "description": "Scaffold Git-tracked repo memory files for ChatGPT and Codex-style coding workflows.",
+  "type": "module",
+  "bin": {
+    "create-chat-gpt-repo-memory": "./bin/cli.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "chatgpt",
+    "codex",
+    "openai",
+    "ai",
+    "agents",
+    "repository",
+    "project-map",
+    "repo-memory",
+    "developer-tools",
+    "cli"
+  ],
+  "license": "MIT",
+  "dependencies": {
+    "commander": "^12.1.0"
+  }
+}

package/src/gitignore.js

@@ -0,0 +1,81 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+
+const GITIGNORE_MARKER = ".agent-memory-local/";
+const GITIGNORE_BLOCK = [
+  "# Local agent memory/cache",
+  ".agent-memory-local/",
+  ".agent-memory/**/*.db",
+  ".agent-memory/**/*.sqlite",
+  ".agent-memory/**/*.sqlite3",
+  ".agent-memory/**/*.log"
+].join("\n");
+
+const LEGACY_PREFIX = "\\." + "chatgpt";
+const LEGACY_PATTERNS = [
+  new RegExp("^# .*" + "chatgpt" + ".*$", "i"),
+  new RegExp(`^${LEGACY_PREFIX}-local/$`),
+  new RegExp(`^${LEGACY_PREFIX}/\\*\\*/\\*\\.db$`),
+  new RegExp(`^${LEGACY_PREFIX}/\\*\\*/\\*\\.sqlite$`),
+  new RegExp(`^${LEGACY_PREFIX}/\\*\\*/\\*\\.sqlite3$`),
+  new RegExp(`^${LEGACY_PREFIX}/\\*\\*/\\*\\.log$`)
+];
+
+function stripLegacyLines(content) {
+  const lines = content.replace(/\r\n/g, "\n").split("\n");
+  const filtered = [];
+  let changed = false;
+
+  for (const line of lines) {
+    const isLegacy = LEGACY_PATTERNS.some((pattern) => pattern.test(line.trim()));
+    if (isLegacy) {
+      changed = true;
+      continue;
+    }
+
+    filtered.push(line);
+  }
+
+  const normalized = filtered.join("\n").replace(/\n{3,}/g, "\n\n");
+  return {
+    changed,
+    content: normalized
+  };
+}
+
+function appendManagedBlock(content) {
+  const trimmed = content.replace(/\s*$/, "");
+  if (trimmed.length === 0) {
+    return `${GITIGNORE_BLOCK}\n`;
+  }
+
+  return `${trimmed}\n\n${GITIGNORE_BLOCK}\n`;
+}
+
+export async function updateGitignoreFile(rootDir) {
+  const gitignorePath = path.join(rootDir, ".gitignore");
+  let current = "";
+
+  try {
+    current = await fs.readFile(gitignorePath, "utf8");
+  } catch (error) {
+    if (error && error.code !== "ENOENT") {
+      throw error;
+    }
+  }
+
+  const { changed: removedLegacy, content: withoutLegacy } = stripLegacyLines(current);
+
+  if (withoutLegacy.includes(GITIGNORE_MARKER)) {
+    if (!removedLegacy) {
+      return "unchanged";
+    }
+
+    await fs.writeFile(gitignorePath, `${withoutLegacy.replace(/\s*$/, "")}\n`, "utf8");
+    return "updated";
+  }
+
+  const nextContent = appendManagedBlock(withoutLegacy);
+  await fs.writeFile(gitignorePath, nextContent, "utf8");
+  return "updated";
+}

package/src/init.js

@@ -0,0 +1,205 @@
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createInterface } from "node:readline/promises";
+import { updateGitignoreFile } from "./gitignore.js";
+import { getProjectName } from "./projectName.js";
+import { getPackageRoot } from "./paths.js";
+import { applyTemplateVariables, validateTemplateName } from "./templateResolver.js";
+
+const GENERATED_BY = "create-chat-gpt-repo-memory";
+const MANAGED_AGENTS_START = "<!-- create-chat-gpt-repo-memory:start -->";
+const MANAGED_AGENTS_END = "<!-- create-chat-gpt-repo-memory:end -->";
+
+const FILES_TO_GENERATE = [
+  { source: "AGENTS.md", target: "AGENTS.md" },
+  { source: "project-map.md", target: ".agent-memory/project-map.md" },
+  { source: "architecture.md", target: ".agent-memory/architecture.md" },
+  { source: "conventions.md", target: ".agent-memory/conventions.md" },
+  { source: "workflows.md", target: ".agent-memory/workflows.md" },
+  { source: "update-project-map.md", target: ".agent-memory/update-project-map.md" },
+  { source: "prompts/fill-project-map.md", target: ".agent-memory/prompts/fill-project-map.md" },
+  { source: "prompts/start-session.md", target: ".agent-memory/prompts/start-session.md" }
+];
+
+const packageRoot = getPackageRoot();
+
+function normalizeNewlines(content) {
+  return content.replace(/\r\n/g, "\n");
+}
+
+function createManagedAgentsBlock(renderedTemplate) {
+  const body = normalizeNewlines(renderedTemplate)
+    .replace(/^# .*?\n+/, "")
+    .trim();
+
+  return [
+    MANAGED_AGENTS_START,
+    "## Repo Memory Instructions",
+    "",
+    body,
+    MANAGED_AGENTS_END
+  ].join("\n");
+}
+
+function isRepoMemoryAwareAgentsFile(content) {
+  return [
+    ".agent-memory/project-map.md",
+    ".agent-memory/",
+    "Use AGENTS.md as your operating instructions",
+    "Project Memory Workflow"
+  ].some((needle) => content.includes(needle));
+}
+
+async function promptForAgentsConflict(relativeTarget) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    return "skip";
+  }
+
+  const readline = createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  try {
+    while (true) {
+      const answer = (await readline.question(
+        `${relativeTarget} already exists and could not be merged automatically. Choose [s]kip or [o]verwrite: `
+      ))
+        .trim()
+        .toLowerCase();
+
+      if (answer === "s" || answer === "skip") {
+        return "skip";
+      }
+
+      if (answer === "o" || answer === "overwrite") {
+        return "overwrite";
+      }
+    }
+  } finally {
+    readline.close();
+  }
+}
+
+async function handleExistingAgentsFile({
+  targetPath,
+  relativeTarget,
+  existingContent,
+  renderedContent,
+  result
+}) {
+  const normalizedExisting = normalizeNewlines(existingContent);
+  const managedBlock = createManagedAgentsBlock(renderedContent);
+
+  if (
+    normalizedExisting.includes(MANAGED_AGENTS_START) &&
+    normalizedExisting.includes(MANAGED_AGENTS_END)
+  ) {
+    const nextContent = normalizedExisting.replace(
+      new RegExp(
+        `${MANAGED_AGENTS_START.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}[\\s\\S]*?${MANAGED_AGENTS_END.replace(/[.*+?^${}()|[\]\\]/g, "\\$&")}`
+      ),
+      managedBlock
+    );
+
+    if (nextContent === normalizedExisting) {
+      result.skipped.push(relativeTarget);
+      return;
+    }
+
+    await fs.writeFile(targetPath, nextContent, "utf8");
+    result.overwritten.push(`${relativeTarget} (merged)`);
+    return;
+  }
+
+  if (!isRepoMemoryAwareAgentsFile(existingContent)) {
+    const nextContent = `${normalizedExisting.trimEnd()}\n\n${managedBlock}\n`;
+    await fs.writeFile(targetPath, nextContent, "utf8");
+    result.overwritten.push(`${relativeTarget} (merged)`);
+    return;
+  }
+
+  const choice = await promptForAgentsConflict(relativeTarget);
+
+  if (choice === "overwrite") {
+    await fs.writeFile(targetPath, renderedContent, "utf8");
+    result.overwritten.push(relativeTarget);
+    return;
+  }
+
+  result.skipped.push(relativeTarget);
+}
+
+export async function initChatGptRepoMemory(options) {
+  const rootDir = path.resolve(options.rootDir);
+  const template = options.template ?? "generic";
+
+  validateTemplateName(template);
+
+  const variables = {
+    PROJECT_NAME: getProjectName(rootDir),
+    TEMPLATE_NAME: template,
+    GENERATED_BY: GENERATED_BY
+  };
+
+  const result = {
+    rootDir,
+    template,
+    created: [],
+    overwritten: [],
+    skipped: [],
+    gitignoreStatus: "skipped"
+  };
+
+  for (const file of FILES_TO_GENERATE) {
+    const templatePath = path.join(packageRoot, "templates", template, file.source);
+    const targetPath = path.join(rootDir, file.target);
+    const relativeTarget = path.relative(rootDir, targetPath) || file.target;
+    const templateContent = await fs.readFile(templatePath, "utf8");
+    const rendered = applyTemplateVariables(templateContent, variables);
+
+    await fs.mkdir(path.dirname(targetPath), { recursive: true });
+
+    let exists = false;
+    try {
+      await fs.access(targetPath);
+      exists = true;
+    } catch (error) {
+      if (error && error.code !== "ENOENT") {
+        throw error;
+      }
+    }
+
+    if (!exists) {
+      await fs.writeFile(targetPath, rendered, "utf8");
+      result.created.push(relativeTarget.replace(/\\/g, "/"));
+      continue;
+    }
+
+    if (options.force) {
+      await fs.writeFile(targetPath, rendered, "utf8");
+      result.overwritten.push(relativeTarget.replace(/\\/g, "/"));
+      continue;
+    }
+
+    if (file.target === "AGENTS.md") {
+      const existingContent = await fs.readFile(targetPath, "utf8");
+      await handleExistingAgentsFile({
+        targetPath,
+        relativeTarget: relativeTarget.replace(/\\/g, "/"),
+        existingContent,
+        renderedContent: rendered,
+        result
+      });
+      continue;
+    }
+
+    result.skipped.push(relativeTarget.replace(/\\/g, "/"));
+  }
+
+  if (options.updateGitignore) {
+    result.gitignoreStatus = await updateGitignoreFile(rootDir);
+  }
+
+  return result;
+}