thomas-agentkit 0.2.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Howard Thomas
+
+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

@@ -32,6 +32,18 @@ Overwrite existing files:
 npx thomas-agentkit init --force
 ```
 
+Update AgentKit-managed template sections:
+
+```bash
+npx thomas-agentkit update
+```
+
+Preview updates without writing files:
+
+```bash
+npx thomas-agentkit update --dry-run
+```
+
 Use the optional interactive flow:
 
 ```bash
@@ -75,6 +87,16 @@ When a preset is selected, AgentKit also installs `STACK.md` and adds a note in
 
 Existing files are skipped by default so local edits are preserved. Use `--force` when you intentionally want to refresh files from the bundled package version.
 
+New installs wrap generated template content in AgentKit managed block markers:
+
+```html
+<!-- agentkit:start agents -->
+Generated content
+<!-- agentkit:end agents -->
+```
+
+`agentkit update` only replaces content inside matching managed blocks. User edits before or after those blocks are preserved. Existing legacy files without managed blocks are reported as unmanaged and left untouched.
+
 ## Presets
 
 Presets add stack-specific guidance without scaffolding framework app files.
@@ -89,6 +111,7 @@ Presets add stack-specific guidance without scaffolding framework app files.
 
 ```text
 agentkit init [target] [--force] [--dry-run] [--interactive] [--yes] [--preset <name>]
+agentkit update [target] [--dry-run] [--preset <name>]
 agentkit --list
 agentkit --list-presets
 agentkit --help
@@ -107,6 +130,8 @@ Options:
 - `-h, --help`: show help
 - `-v, --version`: show package version
 
+For `agentkit update`, `--preset <name>` refreshes preset-specific managed content, including `STACK.md`.
+
 ## Local Development
 
 ```bash
@@ -118,6 +143,35 @@ npm test
 
 The npm package is `thomas-agentkit`. The installed CLI command is `agentkit`, backed by the compiled TypeScript entrypoint at `dist/cli.js`.
 
+## Release
+
+Before publishing a new package version:
+
+1. Update the version in `package.json` intentionally.
+2. Run the full test suite:
+
+   ```bash
+   npm test
+   ```
+
+3. Run the package build step:
+
+   ```bash
+   npm run prepack
+   ```
+
+4. Inspect the publish contents:
+
+   ```bash
+   npm pack --dry-run
+   ```
+
+5. Publish to npm:
+
+   ```bash
+   npm publish
+   ```
+
 ## Philosophy
 
 AgentKit should stay:

package/dist/cli.js

@@ -2,7 +2,7 @@
 import { confirm, isCancel, select, text } from "@clack/prompts";
 import { Command } from "commander";
 import { constants as fsConstants } from "node:fs";
-import { access, copyFile, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, readFile, stat, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 const __filename = fileURLToPath(import.meta.url);
@@ -117,6 +117,19 @@ function resolvePreset(preset) {
 function getStackGuidance(preset) {
     return preset === "fullstack" ? fullstackGuidance : stackGuidance[preset];
 }
+function getTemplateId(file) {
+    return file
+        .replace(/\.[^/.]+$/, "")
+        .replace(/^\./, "")
+        .split("/")
+        .filter(Boolean)
+        .join("-")
+        .toLowerCase();
+}
+function wrapManagedBlock(file, content) {
+    const id = getTemplateId(file);
+    return `<!-- agentkit:start ${id} -->\n${content.trimEnd()}\n<!-- agentkit:end ${id} -->\n`;
+}
 function addStackReference(file, content, preset) {
     if (file !== "AGENTS.md" || !preset) {
         return content;
@@ -149,10 +162,11 @@ async function installTemplates(targetArg, options) {
             await mkdir(path.dirname(destination), { recursive: true });
             if (preset && file === "AGENTS.md") {
                 const content = await readFile(source, "utf8");
-                await writeFile(destination, addStackReference(file, content, preset));
+                await writeFile(destination, wrapManagedBlock(file, addStackReference(file, content, preset)));
             }
             else {
-                await copyFile(source, destination);
+                const content = await readFile(source, "utf8");
+                await writeFile(destination, wrapManagedBlock(file, content));
             }
         }
     }
@@ -166,12 +180,84 @@ async function installTemplates(targetArg, options) {
         else {
             created.push(stackFile);
             if (!options.dryRun) {
-                await writeFile(destination, getStackGuidance(preset));
+                await writeFile(destination, wrapManagedBlock(stackFile, getStackGuidance(preset)));
             }
         }
     }
     return { targetDir, created, skipped };
 }
+function replaceManagedBlock(file, existingContent, nextContent) {
+    const id = getTemplateId(file);
+    const startMarker = `<!-- agentkit:start ${id} -->`;
+    const endMarker = `<!-- agentkit:end ${id} -->`;
+    const startIndex = existingContent.indexOf(startMarker);
+    const endIndex = existingContent.indexOf(endMarker);
+    if (startIndex === -1 && endIndex === -1) {
+        return undefined;
+    }
+    if (startIndex === -1 || endIndex === -1 || endIndex < startIndex) {
+        throw new Error(`Malformed managed block in ${file}.`);
+    }
+    const afterEndIndex = endIndex + endMarker.length;
+    const replacement = wrapManagedBlock(file, nextContent).trimEnd();
+    return `${existingContent.slice(0, startIndex)}${replacement}${existingContent.slice(afterEndIndex)}`;
+}
+async function buildTemplateContent(file, preset) {
+    if (file === "STACK.md") {
+        if (!preset) {
+            throw new Error("STACK.md requires a preset.");
+        }
+        return getStackGuidance(preset);
+    }
+    const source = path.join(templatesDir, file);
+    const content = await readFile(source, "utf8");
+    return addStackReference(file, content, preset);
+}
+async function updateTemplates(targetArg, options) {
+    const targetDir = path.resolve(process.cwd(), targetArg || ".");
+    const preset = resolvePreset(options.preset);
+    const files = preset ? [...(await getTemplateFiles()), "STACK.md"] : await getTemplateFiles();
+    const created = [];
+    const updated = [];
+    const skipped = [];
+    const malformed = [];
+    const unchanged = [];
+    for (const file of files) {
+        const destination = path.join(targetDir, file);
+        const nextContent = await buildTemplateContent(file, preset);
+        const destinationExists = await exists(destination);
+        if (!destinationExists) {
+            created.push(file);
+            if (!options.dryRun) {
+                await mkdir(path.dirname(destination), { recursive: true });
+                await writeFile(destination, wrapManagedBlock(file, nextContent));
+            }
+            continue;
+        }
+        const existingContent = await readFile(destination, "utf8");
+        let updatedContent;
+        try {
+            updatedContent = replaceManagedBlock(file, existingContent, nextContent);
+        }
+        catch {
+            malformed.push(file);
+            continue;
+        }
+        if (updatedContent === undefined) {
+            skipped.push(file);
+            continue;
+        }
+        if (updatedContent === existingContent) {
+            unchanged.push(file);
+            continue;
+        }
+        updated.push(file);
+        if (!options.dryRun) {
+            await writeFile(destination, updatedContent);
+        }
+    }
+    return { targetDir, created, updated, skipped, malformed, unchanged };
+}
 function printInstallResult(result, dryRun = false) {
     const action = dryRun ? "Would install" : "Installed";
     console.log(`${action} AgentKit files in ${result.targetDir}`);
@@ -186,6 +272,33 @@ function printInstallResult(result, dryRun = false) {
         console.log("No bundled templates found.");
     }
 }
+function printUpdateResult(result, dryRun = false) {
+    const action = dryRun ? "Would update" : "Updated";
+    console.log(`${action} AgentKit files in ${result.targetDir}`);
+    if (result.created.length > 0) {
+        console.log(`${dryRun ? "Would create" : "Created"}: ${result.created.join(", ")}`);
+    }
+    if (result.updated.length > 0) {
+        console.log(`${dryRun ? "Would update" : "Updated"}: ${result.updated.join(", ")}`);
+    }
+    if (result.unchanged.length > 0) {
+        console.log(`Already current: ${result.unchanged.join(", ")}`);
+    }
+    if (result.skipped.length > 0) {
+        console.log(`Skipped unmanaged: ${result.skipped.join(", ")}`);
+        console.log("Add AgentKit managed block markers before updating these files.");
+    }
+    if (result.malformed.length > 0) {
+        console.log(`Skipped malformed: ${result.malformed.join(", ")}`);
+        console.log("Fix AgentKit managed block markers before updating these files.");
+    }
+    if (result.created.length === 0 &&
+        result.updated.length === 0 &&
+        result.skipped.length === 0 &&
+        result.malformed.length === 0) {
+        console.log("All managed AgentKit files are current.");
+    }
+}
 async function resolveInteractiveTarget(target, options) {
     const providedPreset = resolvePreset(options.preset);
     if (!options.interactive) {
@@ -250,6 +363,7 @@ async function main() {
 
 Examples:
   agentkit init
+  agentkit update
   agentkit init --preset next
   agentkit init ./my-project --dry-run
   agentkit --list-presets
@@ -268,6 +382,16 @@ Examples:
         const result = await installTemplates(resolvedTarget, options);
         printInstallResult(result, Boolean(options.dryRun));
     });
+    program
+        .command("update")
+        .description("update AgentKit managed template blocks in a project")
+        .argument("[target]", "target project directory", ".")
+        .option("--dry-run", "print planned changes without writing files")
+        .option("--preset <name>", `update stack-specific guidance (${formatPresetList()})`)
+        .action(async (target, options) => {
+        const result = await updateTemplates(target, options);
+        printUpdateResult(result, Boolean(options.dryRun));
+    });
     await program.parseAsync(process.argv);
 }
 main().catch((error) => {

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "thomas-agentkit",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Install AI-agent-ready development templates into a project.",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/howie1329/Howard-AgentKit.git"
+  },
+  "homepage": "https://github.com/howie1329/Howard-AgentKit#readme",
+  "bugs": {
+    "url": "https://github.com/howie1329/Howard-AgentKit/issues"
+  },
+  "keywords": [
+    "agentkit",
+    "ai",
+    "agents",
+    "codex",
+    "cli",
+    "scaffolding",
+    "templates"
+  ],
   "type": "module",
   "bin": {
     "agentkit": "./dist/cli.js"