agenttwin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 AgentTwin
+
+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,48 @@
+# agenttwin
+
+**Give your agent a test world before it touches the real one.**
+
+A safe, executable copy of the systems your agent reads from and writes to, so you
+can run the same workflow against a replica, inject real failure conditions, and
+turn a discovered failure into a regression test.
+
+> **Early preview.** This package is the CLI shell for that vision. `agenttwin init`
+> works today. The runtime commands (`up`, `run`, `fault`, `diff`, `adopt`) are
+> coming soon.
+
+## Usage
+
+```sh
+npx agenttwin init
+```
+
+Writes a starter `agenttwin.config.json` into the current directory:
+
+```json
+{
+  "version": 1,
+  "world": "default",
+  "twins": []
+}
+```
+
+Re-run with `--force` to overwrite an existing config.
+
+```sh
+npx agenttwin --help
+npx agenttwin --version
+```
+
+## Requirements
+
+Node.js 18 or newer.
+
+## Status
+
+`agenttwin init` is the only implemented command. Nothing here connects to real
+providers, requests credentials, or executes code. See the project repository for
+the product thesis and roadmap.
+
+## License
+
+MIT

package/dist/cli.js

@@ -0,0 +1,135 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { readFileSync } from "fs";
+import { dirname, join as join2 } from "path";
+import { fileURLToPath } from "url";
+import { parseArgs } from "util";
+
+// src/lib/logger.ts
+var useColor = process.stdout.isTTY === true && process.env.NO_COLOR === void 0;
+function style(code) {
+  return (text) => useColor ? `\x1B[${code}m${text}\x1B[0m` : text;
+}
+var bold = style(1);
+var dim = style(2);
+var green = style(32);
+var red = style(31);
+function ok(message) {
+  console.log(`${green("\u2713")} ${message}`);
+}
+function info(message = "") {
+  console.log(message);
+}
+function fail(message) {
+  console.error(`${red("\u2717")} ${message}`);
+}
+
+// src/lib/config.ts
+import { existsSync } from "fs";
+import { writeFile } from "fs/promises";
+import { join } from "path";
+var CONFIG_FILENAME = "agenttwin.config.json";
+var DEFAULT_CONFIG = {
+  version: 1,
+  world: "default",
+  twins: []
+};
+function configPath(cwd) {
+  return join(cwd, CONFIG_FILENAME);
+}
+async function writeConfig(cwd, { force = false } = {}) {
+  const path = configPath(cwd);
+  if (existsSync(path) && !force) {
+    throw new Error(
+      `${CONFIG_FILENAME} already exists. Re-run with --force to overwrite it.`
+    );
+  }
+  await writeFile(path, `${JSON.stringify(DEFAULT_CONFIG, null, 2)}
+`, "utf8");
+  return { path };
+}
+
+// src/commands/init.ts
+async function runInit({ cwd, force }) {
+  const { path } = await writeConfig(cwd, { force });
+  ok(`Created ${CONFIG_FILENAME}`);
+  info(dim(`   ${path}`));
+  info();
+  info(`Next: ${bold("npx agenttwin run")} on your workflow ${dim("(coming soon)")}`);
+}
+
+// src/cli.ts
+var PLANNED = ["up", "run", "fault", "diff", "adopt"];
+function readVersion() {
+  const here = dirname(fileURLToPath(import.meta.url));
+  const pkg = JSON.parse(
+    readFileSync(join2(here, "..", "package.json"), "utf8")
+  );
+  return pkg.version ?? "0.0.0";
+}
+function helpText() {
+  return [
+    `${bold("agenttwin")} ${dim("\u2014 give your agent a test world before it touches the real one.")}`,
+    "",
+    bold("Usage"),
+    "  $ npx agenttwin <command> [options]",
+    "",
+    bold("Commands"),
+    `  ${"init".padEnd(14)}Write a starter agenttwin.config.json`,
+    "",
+    bold("Coming soon"),
+    `  ${PLANNED.join(", ")}`,
+    "",
+    bold("Options"),
+    `  ${"-v, --version".padEnd(14)}Print the installed version`,
+    `  ${"-h, --help".padEnd(14)}Show this help`
+  ].join("\n");
+}
+async function main() {
+  let values;
+  let positionals;
+  try {
+    const parsed = parseArgs({
+      args: process.argv.slice(2),
+      allowPositionals: true,
+      options: {
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+        force: { type: "boolean" }
+      }
+    });
+    values = parsed.values;
+    positionals = parsed.positionals;
+  } catch (error) {
+    fail(error instanceof Error ? error.message : String(error));
+    info();
+    info(helpText());
+    process.exitCode = 1;
+    return;
+  }
+  if (values.version) {
+    process.stdout.write(`${readVersion()}
+`);
+    return;
+  }
+  if (values.help || positionals.length === 0) {
+    info(helpText());
+    return;
+  }
+  const [command] = positionals;
+  switch (command) {
+    case "init":
+      await runInit({ cwd: process.cwd(), force: values.force === true });
+      return;
+    default:
+      fail(`Unknown command: ${command}`);
+      info();
+      info(helpText());
+      process.exitCode = 1;
+  }
+}
+main().catch((error) => {
+  fail(error instanceof Error ? error.message : String(error));
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "agenttwin",
+  "version": "0.1.0",
+  "description": "Give your agent a test world before it touches the real one.",
+  "keywords": [
+    "agent",
+    "ai",
+    "testing",
+    "simulation",
+    "sandbox",
+    "twin",
+    "cli"
+  ],
+  "type": "module",
+  "bin": {
+    "agenttwin": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsx src/cli.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.4",
+    "tsup": "^8.5.1",
+    "tsx": "^4.23.15",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
+  }
+}