@ratio-app/cli 0.1.1

package/dist/commands/app/create.js

@@ -0,0 +1,609 @@
+// src/commands/app/create.ts
+import { existsSync, readFileSync, statSync } from "fs";
+import { dirname as dirname2, join as join2, resolve as resolve2 } from "path";
+import { fileURLToPath as fileURLToPath2 } from "url";
+import { Args, Flags as Flags2 } from "@oclif/core";
+
+// src/lib/errors.ts
+var RatioCLIError = class extends Error {
+  code;
+  exitCode;
+  hint;
+  docsUrl;
+  constructor(opts) {
+    super(opts.message);
+    this.name = new.target.name;
+    this.code = opts.code;
+    this.exitCode = opts.exitCode;
+    if (opts.hint !== void 0) this.hint = opts.hint;
+    if (opts.docsUrl !== void 0) this.docsUrl = opts.docsUrl;
+  }
+};
+var TemplateExistsError = class extends RatioCLIError {
+  constructor(message, hint = "Choose a different name or remove the existing directory.") {
+    super({ code: "TEMPLATE_EXISTS", exitCode: 7, message, hint });
+  }
+};
+var ValidationError = class extends RatioCLIError {
+  constructor(message, hint) {
+    const opts = {
+      code: "VALIDATION_ERROR",
+      exitCode: 8,
+      message
+    };
+    if (hint !== void 0) opts.hint = hint;
+    super(opts);
+  }
+};
+function isRatioCLIError(err) {
+  return err instanceof RatioCLIError;
+}
+
+// src/lib/ratio-command.ts
+import { Command, Errors } from "@oclif/core";
+
+// src/lib/render-error.ts
+function isOclifParserError(err) {
+  return err instanceof Error && "parse" in err && err.parse !== null && err.parse !== void 0;
+}
+function buildErrorEnvelope(code, message, hint, docsUrl) {
+  const obj = { ok: false, code, message };
+  if (hint !== void 0) obj["hint"] = hint;
+  if (docsUrl !== void 0) obj["docsUrl"] = docsUrl;
+  return JSON.stringify(obj) + "\n";
+}
+function renderError(input) {
+  const { err, verbose, json } = input;
+  if (isRatioCLIError(err)) {
+    const ratioErr = err;
+    if (ratioErr.exitCode === 0) {
+      if (json) {
+        return {
+          stdout: JSON.stringify({ ok: true, data: null }) + "\n",
+          stderr: "",
+          exitCode: 0
+        };
+      }
+      return {
+        stdout: ratioErr.message + "\n",
+        stderr: "",
+        exitCode: 0
+      };
+    }
+    let stderrLines = `${ratioErr.code}: ${ratioErr.message}
+`;
+    if (ratioErr.hint !== void 0) stderrLines += `${ratioErr.hint}
+`;
+    if (ratioErr.docsUrl !== void 0) stderrLines += `${ratioErr.docsUrl}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(ratioErr.code, ratioErr.message, ratioErr.hint, ratioErr.docsUrl),
+        stderr: verbose && ratioErr.stack ? ratioErr.stack + "\n" : "",
+        exitCode: ratioErr.exitCode
+      };
+    }
+    if (verbose && ratioErr.stack) {
+      stderrLines += ratioErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrLines, exitCode: ratioErr.exitCode };
+  }
+  if (isOclifParserError(err)) {
+    const parserErr = err;
+    const msg = parserErr.message || "Unknown parse error";
+    const coercedErr = new ValidationError(msg);
+    let stderrText2 = `${coercedErr.code}: ${msg}
+`;
+    if (json) {
+      return {
+        stdout: buildErrorEnvelope(coercedErr.code, msg),
+        stderr: verbose && parserErr.stack ? parserErr.stack + "\n" : "",
+        exitCode: 8
+      };
+    }
+    if (verbose && parserErr.stack) {
+      stderrText2 += parserErr.stack + "\n";
+    }
+    return { stdout: "", stderr: stderrText2, exitCode: 8 };
+  }
+  const message = err instanceof Error ? err.message : String(err);
+  const stack = err instanceof Error ? err.stack : void 0;
+  const stderrPrefix = `INTERNAL: ${message}
+`;
+  if (json) {
+    return {
+      stdout: buildErrorEnvelope("INTERNAL", message),
+      stderr: verbose && stack ? stack + "\n" : "",
+      exitCode: 1
+    };
+  }
+  let stderrText = stderrPrefix;
+  if (verbose && stack) {
+    stderrText += stack + "\n";
+  }
+  return { stdout: "", stderr: stderrText, exitCode: 1 };
+}
+
+// src/lib/ratio-command.ts
+var RatioCommand = class extends Command {
+  _getRenderFlags() {
+    const argv = this.argv;
+    return {
+      verbose: argv.includes("--verbose"),
+      json: argv.includes("--json")
+    };
+  }
+  async catch(err) {
+    const { verbose, json } = this._getRenderFlags();
+    const output = renderError({ err, verbose, json });
+    if (output.stdout) process.stdout.write(output.stdout);
+    if (output.stderr) process.stderr.write(output.stderr);
+    if (output.exitCode === 0) {
+      throw new Errors.ExitError(0);
+    }
+    err.skipOclifErrorHandling = true;
+    err.oclif = { exit: output.exitCode };
+    throw err;
+  }
+};
+
+// src/lib/verbose-flag.ts
+import { Flags } from "@oclif/core";
+var verboseFlag = {
+  verbose: Flags.boolean({
+    description: "Show diagnostic detail: HTTP status/timing lines for auth requests (stderr) and stack traces for internal errors."
+  })
+};
+var jsonFlag = {
+  json: Flags.boolean({
+    description: "Emit machine-readable JSON on stdout."
+  })
+};
+
+// src/scaffold/render.ts
+import { copyFile, mkdir, readFile, readdir, stat, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+var RatioTemplateError = class extends Error {
+  code;
+  templateName;
+  key;
+  constructor(opts) {
+    super(opts.message, opts.cause === void 0 ? void 0 : { cause: opts.cause });
+    this.name = "RatioTemplateError";
+    this.code = opts.code;
+    if (opts.templateName !== void 0) {
+      this.templateName = opts.templateName;
+    }
+    if (opts.key !== void 0) {
+      this.key = opts.key;
+    }
+  }
+};
+var PLACEHOLDER_REGEX = /\{\{([a-zA-Z][a-zA-Z0-9_]*)\}\}/g;
+var TMPL_SUFFIX = ".tmpl";
+async function isDirectory(path) {
+  try {
+    return (await stat(path)).isDirectory();
+  } catch {
+    return false;
+  }
+}
+async function discoverSourceRoot(sourceRootOverride) {
+  if (sourceRootOverride !== void 0) {
+    return sourceRootOverride;
+  }
+  const moduleDir = dirname(fileURLToPath(import.meta.url));
+  const candidates = [join(moduleDir, "templates"), resolve(moduleDir, "..", "templates")];
+  for (const candidate of candidates) {
+    if (await isDirectory(candidate)) {
+      return candidate;
+    }
+  }
+  throw new RatioTemplateError({
+    code: "io_error",
+    message: `templates root not found (looked in: ${candidates.join(", ")})`
+  });
+}
+function assertManifestShape(raw, path) {
+  if (typeof raw !== "object" || raw === null || typeof raw.name !== "string" || typeof raw.description !== "string" || !Array.isArray(raw.substitutionKeys) || !raw.substitutionKeys.every(
+    (k) => typeof k === "string"
+  )) {
+    throw new RatioTemplateError({
+      code: "io_error",
+      message: `invalid template manifest at ${path}: expected { name, description, substitutionKeys[] }`
+    });
+  }
+  const shaped = raw;
+  return {
+    name: shaped.name,
+    description: shaped.description,
+    substitutionKeys: shaped.substitutionKeys
+  };
+}
+async function loadManifest(templateRoot) {
+  const manifestPath = join(templateRoot, "manifest.json");
+  let content;
+  try {
+    content = await readFile(manifestPath, "utf8");
+  } catch (err) {
+    throw new RatioTemplateError({
+      code: "io_error",
+      message: `failed to read template manifest at ${manifestPath}`,
+      cause: err
+    });
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(content);
+  } catch (err) {
+    throw new RatioTemplateError({
+      code: "io_error",
+      message: `template manifest at ${manifestPath} is not valid JSON`,
+      cause: err
+    });
+  }
+  return assertManifestShape(parsed, manifestPath);
+}
+function substituteContent(content, substitutions, allowedKeys, templateName) {
+  return content.replace(PLACEHOLDER_REGEX, (_match, key) => {
+    if (!allowedKeys.has(key)) {
+      throw new RatioTemplateError({
+        code: "unknown_substitution_key",
+        message: `placeholder {{${key}}} is not declared in the template manifest's substitutionKeys`,
+        templateName,
+        key
+      });
+    }
+    const value = substitutions[key];
+    if (value === void 0) {
+      throw new RatioTemplateError({
+        code: "missing_substitution_value",
+        message: `no substitution value provided for {{${key}}}`,
+        templateName,
+        key
+      });
+    }
+    return value;
+  });
+}
+async function walkTemplateTree(root, relative = "") {
+  const entries = await readdir(join(root, relative), { withFileTypes: true });
+  entries.sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
+  const files = [];
+  for (const entry of entries) {
+    const rel = relative === "" ? entry.name : join(relative, entry.name);
+    if (entry.isDirectory()) {
+      files.push(...await walkTemplateTree(root, rel));
+    } else {
+      files.push({ relativePath: rel, absolutePath: join(root, rel) });
+    }
+  }
+  return files;
+}
+async function renderTemplate(input) {
+  const sourceRoot = await discoverSourceRoot(input.sourceRootOverride);
+  const templateRoot = join(sourceRoot, input.templateName);
+  if (!await isDirectory(templateRoot)) {
+    throw new RatioTemplateError({
+      code: "template_not_found",
+      message: `template '${input.templateName}' not found under ${sourceRoot}`,
+      templateName: input.templateName
+    });
+  }
+  const manifest = await loadManifest(templateRoot);
+  const allowedKeys = new Set(manifest.substitutionKeys);
+  try {
+    const existing = await readdir(input.destinationDir);
+    if (existing.length > 0) {
+      throw new RatioTemplateError({
+        code: "destination_not_empty",
+        message: `destination directory ${input.destinationDir} is not empty`,
+        templateName: input.templateName
+      });
+    }
+  } catch (err) {
+    if (err instanceof RatioTemplateError) {
+      throw err;
+    }
+    if (err.code !== "ENOENT") {
+      throw new RatioTemplateError({
+        code: "io_error",
+        message: `failed to inspect destination directory ${input.destinationDir}`,
+        templateName: input.templateName,
+        cause: err
+      });
+    }
+  }
+  let files;
+  try {
+    files = await walkTemplateTree(templateRoot);
+  } catch (err) {
+    throw new RatioTemplateError({
+      code: "io_error",
+      message: `failed to walk template tree at ${templateRoot}`,
+      templateName: input.templateName,
+      cause: err
+    });
+  }
+  const filesWritten = [];
+  let bytesWritten = 0;
+  for (const file of files) {
+    const isTmpl = file.relativePath.endsWith(TMPL_SUFFIX);
+    const outRelative = isTmpl ? file.relativePath.slice(0, -TMPL_SUFFIX.length) : file.relativePath;
+    const isTopLevelGitignore = file.relativePath === "gitignore";
+    const effectiveOutRelative = isTopLevelGitignore ? ".gitignore" : outRelative;
+    const outPath = join(input.destinationDir, effectiveOutRelative);
+    let perFileBytes = 0;
+    if (isTmpl) {
+      let raw;
+      try {
+        raw = await readFile(file.absolutePath, "utf8");
+      } catch (err) {
+        throw new RatioTemplateError({
+          code: "io_error",
+          message: `failed to read template file ${file.absolutePath}`,
+          templateName: input.templateName,
+          cause: err
+        });
+      }
+      const rendered = substituteContent(
+        raw,
+        input.substitutions,
+        allowedKeys,
+        input.templateName
+      );
+      try {
+        await mkdir(dirname(outPath), { recursive: true });
+        await writeFile(outPath, rendered, "utf8");
+      } catch (err) {
+        throw new RatioTemplateError({
+          code: "io_error",
+          message: `failed to write rendered file ${outPath}`,
+          templateName: input.templateName,
+          cause: err
+        });
+      }
+      perFileBytes = Buffer.byteLength(rendered, "utf8");
+      bytesWritten += perFileBytes;
+    } else {
+      try {
+        await mkdir(dirname(outPath), { recursive: true });
+        await copyFile(file.absolutePath, outPath);
+        perFileBytes = (await stat(outPath)).size;
+        bytesWritten += perFileBytes;
+      } catch (err) {
+        throw new RatioTemplateError({
+          code: "io_error",
+          message: `failed to copy file ${file.absolutePath} to ${outPath}`,
+          templateName: input.templateName,
+          cause: err
+        });
+      }
+    }
+    filesWritten.push(outPath);
+    if (input.onFile !== void 0) {
+      try {
+        input.onFile(effectiveOutRelative, perFileBytes);
+      } catch (err) {
+        throw new RatioTemplateError({
+          code: "io_error",
+          message: "onFile callback threw",
+          templateName: input.templateName,
+          cause: err
+        });
+      }
+    }
+  }
+  return { filesWritten, bytesWritten };
+}
+
+// src/commands/app/create.ts
+var TEMPLATE_OPTIONS = ["minimal", "with-admin-ui", "serverless"];
+var APP_NAME_PLACEHOLDER = "<APP_NAME>";
+function nextSteps(template) {
+  const common = {
+    cd: `cd ${APP_NAME_PLACEHOLDER}`,
+    install: "npm install",
+    config: "Open ratio.config.jsonc and paste the client id (or run 'ratio app link').",
+    endpoints: "Point your merchant test store at the /oauth/callback and /webhooks endpoints (use 'ratio dev listen' for local testing)."
+  };
+  if (template === "minimal") {
+    return [
+      common.cd,
+      common.install,
+      common.config,
+      "Copy .env.example to .env and fill RATIO_CLIENT_SECRET + RATIO_WEBHOOK_SECRET.",
+      "Run npm run dev to start the local server on port 3000.",
+      common.endpoints
+    ];
+  }
+  if (template === "with-admin-ui") {
+    return [
+      common.cd,
+      common.install,
+      common.config,
+      "Copy .env.example to .env and fill RATIO_CLIENT_SECRET + RATIO_WEBHOOK_SECRET.",
+      "Run npm run dev to start the API server on port 3000, and npm run admin:dev to start the admin UI on http://localhost:3001.",
+      common.endpoints
+    ];
+  }
+  return [
+    common.cd,
+    common.install,
+    common.config,
+    "Set your secrets with 'wrangler secret put RATIO_CLIENT_SECRET' and 'wrangler secret put RATIO_WEBHOOK_SECRET'.",
+    "Run npm run dev to start wrangler dev locally, then npm run deploy when ready.",
+    "Point your merchant test store at your workers.dev route's /oauth/callback and /webhooks endpoints."
+  ];
+}
+function formatNextSteps(template, appName) {
+  return nextSteps(template).map(
+    (step) => step.replace(APP_NAME_PLACEHOLDER, appName)
+  );
+}
+function readOwnSdkVersion(startDir = dirname2(fileURLToPath2(import.meta.url))) {
+  let dir = startDir;
+  for (; ; ) {
+    const candidate = join2(dir, "package.json");
+    if (existsSync(candidate)) {
+      const parsed = JSON.parse(readFileSync(candidate, "utf8"));
+      const version = parsed.dependencies?.["@ratio-app/sdk"];
+      if (typeof version === "string" && version.length > 0) {
+        return version;
+      }
+    }
+    const parent = dirname2(dir);
+    if (parent === dir) {
+      throw new Error(
+        "Could not locate the CLI package.json with an @ratio-app/sdk dependency."
+      );
+    }
+    dir = parent;
+  }
+}
+function discoverTemplatesRoot(startDir = dirname2(fileURLToPath2(import.meta.url))) {
+  let dir = startDir;
+  for (; ; ) {
+    const candidate = join2(dir, "templates");
+    if (existsSync(candidate) && statSync(candidate).isDirectory()) {
+      return candidate;
+    }
+    const atPackageRoot = existsSync(join2(dir, "package.json"));
+    const parent = dirname2(dir);
+    if (atPackageRoot || parent === dir) {
+      throw new Error(
+        `Could not locate the bundled templates directory (walked up from ${startDir}).`
+      );
+    }
+    dir = parent;
+  }
+}
+var AppCreate = class _AppCreate extends RatioCommand {
+  static description = "Create a new Ratio app from a template.";
+  static examples = [
+    "<%= config.bin %> app create my-app",
+    "<%= config.bin %> app create my-app --template=serverless",
+    "<%= config.bin %> app create my-app --json"
+  ];
+  static args = {
+    name: Args.string({
+      name: "name",
+      required: true,
+      description: "Directory name for the new Ratio app."
+    })
+  };
+  static flags = {
+    ...verboseFlag,
+    ...jsonFlag,
+    template: Flags2.string({
+      options: [...TEMPLATE_OPTIONS],
+      default: "minimal",
+      description: "Template to scaffold from."
+    })
+  };
+  // ── Seams: overridable in tests; defaults hit the real process. ──────────
+  writeOut = (chunk) => {
+    process.stdout.write(chunk);
+  };
+  writeErr = (chunk) => {
+    process.stderr.write(chunk);
+  };
+  renderTemplate = renderTemplate;
+  async run() {
+    const { args, flags } = await this.parse(_AppCreate);
+    const jsonMode = flags.json === true;
+    const verbose = flags.verbose === true;
+    const template = flags.template;
+    const trace = (message) => {
+      if (verbose) {
+        this.writeErr(`${message}
+`);
+      }
+    };
+    const destinationDir = resolve2(process.cwd(), args.name);
+    const sdkVersion = readOwnSdkVersion();
+    trace(`template: ${template}`);
+    trace(`destination: ${destinationDir}`);
+    const substitutions = {
+      appName: args.name,
+      // Intentionally empty — `ratio app link` fills it later.
+      clientId: "",
+      sdkVersion,
+      templateName: template
+    };
+    let result;
+    const started = Date.now();
+    try {
+      const input = {
+        templateName: template,
+        destinationDir,
+        substitutions,
+        // The built CLI bundles this command with its own copy of the
+        // engine, so the engine's dist-relative discovery does not apply
+        // here; the command resolves the templates root itself.
+        sourceRootOverride: discoverTemplatesRoot(),
+        ...verbose ? {
+          onFile: (relativePath) => {
+            this.writeErr(`wrote ${relativePath}
+`);
+          }
+        } : {}
+      };
+      result = await this.renderTemplate(input);
+    } catch (err) {
+      if (err instanceof RatioTemplateError) {
+        if (err.code === "destination_not_empty") {
+          throw new TemplateExistsError(`Directory '${args.name}' is not empty.`);
+        }
+        if (err.code === "template_not_found") {
+          throw new ValidationError(
+            `Unknown template '${template}'.`,
+            "Use --template=minimal|with-admin-ui|serverless."
+          );
+        }
+        throw new RatioCLIError({
+          code: "TEMPLATE_IO",
+          exitCode: 1,
+          message: err.message
+        });
+      }
+      throw err;
+    }
+    trace(`rendered in ${Date.now() - started}ms`);
+    const steps = formatNextSteps(template, args.name);
+    if (jsonMode) {
+      this.writeOut(
+        `${JSON.stringify({
+          ok: true,
+          data: {
+            template,
+            path: destinationDir,
+            filesWritten: result.filesWritten.length,
+            next: steps
+          }
+        })}
+`
+      );
+      return;
+    }
+    const numbered = steps.map((step, i) => `  ${i + 1}. ${step}`).join("\n");
+    this.writeOut(
+      `Created ${args.name} from the ${template} template (${result.filesWritten.length} files, ${result.bytesWritten} bytes).
+
+Next steps:
+${numbered}
+`
+    );
+  }
+};
+export {
+  APP_NAME_PLACEHOLDER,
+  TEMPLATE_OPTIONS,
+  AppCreate as default,
+  discoverTemplatesRoot,
+  formatNextSteps,
+  nextSteps,
+  readOwnSdkVersion
+};
+//# sourceMappingURL=create.js.map