slskit-cli 1.0.0

package/dist/core/environments.js

@@ -0,0 +1,161 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FUNCTION_NAME_MAX = exports.APP_ENVIRONMENT_PARAM = exports.APP_ENVIRONMENT_KEY = exports.DEFAULT_ENVIRONMENT = exports.LEGACY_MANIFEST_FILE = exports.MANIFEST_FILE = void 0;
+exports.manifestPathFor = manifestPathFor;
+exports.readManifest = readManifest;
+exports.writeManifest = writeManifest;
+exports.parseEnvironmentName = parseEnvironmentName;
+exports.environmentNames = environmentNames;
+exports.defaultEnvironment = defaultEnvironment;
+exports.resolveEnvironmentName = resolveEnvironmentName;
+exports.requireEnvironment = requireEnvironment;
+exports.stackNameFor = stackNameFor;
+exports.functionNameFor = functionNameFor;
+exports.assertFunctionNameFits = assertFunctionNameFits;
+exports.envVarSource = envVarSource;
+exports.allEnvKeys = allEnvKeys;
+exports.writeEnvironment = writeEnvironment;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+exports.MANIFEST_FILE = "slskit.json";
+// The manifest was called sless.json before the CLI was renamed. Projects generated
+// then are still read, and migrated to the new name the next time one is written.
+exports.LEGACY_MANIFEST_FILE = "sless.json";
+// The manifest this project actually has on disk, new name preferred.
+function manifestPathFor(cwd) {
+    for (const name of [exports.MANIFEST_FILE, exports.LEGACY_MANIFEST_FILE]) {
+        const candidate = node_path_1.default.join(cwd, name);
+        if (node_fs_1.default.existsSync(candidate)) {
+            return candidate;
+        }
+    }
+    return undefined;
+}
+// Every project has this environment from "slskit init" onward, and every
+// stage-aware command falls back to it when no --env is given.
+exports.DEFAULT_ENVIRONMENT = "dev";
+// The variable slskit always generates. Its value is the environment name, and
+// every stage-scoped resource name is built from it.
+exports.APP_ENVIRONMENT_KEY = "APP_ENVIRONMENT";
+// The matching CloudFormation parameter. Templates are shared by every
+// environment, so the name has to arrive as an override at deploy time.
+exports.APP_ENVIRONMENT_PARAM = "AppEnvironment";
+// Lambda caps a function name at 64 characters, and slskit builds it as
+// <project>-<environment>-<function>.
+exports.FUNCTION_NAME_MAX = 64;
+const ENVIRONMENT_PATTERN = /^[a-z][a-z0-9-]*$/;
+function readManifest(cwd, command = "slskit") {
+    const manifestPath = manifestPathFor(cwd);
+    if (!manifestPath) {
+        throw new errors_js_1.CliError(`No ${exports.MANIFEST_FILE} found in ${cwd}. Run "slskit init" first, or run "${command}" from your project root.`);
+    }
+    let manifest;
+    try {
+        manifest = JSON.parse(node_fs_1.default.readFileSync(manifestPath, "utf8"));
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        throw new errors_js_1.CliError(`${exports.MANIFEST_FILE} is not valid JSON: ${message}`);
+    }
+    if (!manifest?.name) {
+        throw new errors_js_1.CliError(`${exports.MANIFEST_FILE} is missing a project "name".`);
+    }
+    return manifest;
+}
+function writeManifest(cwd, manifest) {
+    node_fs_1.default.writeFileSync(node_path_1.default.join(cwd, exports.MANIFEST_FILE), `${JSON.stringify(manifest, null, 2)}\n`);
+    // Writing completes the rename: leaving both files behind would make it ambiguous
+    // which one a command had actually read.
+    const legacy = node_path_1.default.join(cwd, exports.LEGACY_MANIFEST_FILE);
+    if (node_fs_1.default.existsSync(legacy)) {
+        node_fs_1.default.rmSync(legacy);
+    }
+}
+function parseEnvironmentName(value, label = "Environment name") {
+    if (value === undefined || value.trim() === "") {
+        return undefined;
+    }
+    const name = value.trim().toLowerCase();
+    if (!ENVIRONMENT_PATTERN.test(name)) {
+        throw new errors_js_1.CliError(`Invalid ${label.toLowerCase()} "${value}". Use lowercase letters, digits and hyphens, starting with a letter (for example: dev, staging, stage-1, production).`);
+    }
+    return name;
+}
+function environmentNames(manifest) {
+    return Object.keys(manifest.environments?.list ?? {}).sort();
+}
+function defaultEnvironment(manifest) {
+    return manifest.environments?.default ?? exports.DEFAULT_ENVIRONMENT;
+}
+function resolveEnvironmentName(manifest, requested) {
+    return parseEnvironmentName(requested) ?? defaultEnvironment(manifest);
+}
+function requireEnvironment(manifest, name) {
+    const config = manifest.environments?.list?.[name];
+    if (!config) {
+        const known = environmentNames(manifest).join(", ") || "(none)";
+        throw new errors_js_1.CliError(`Environment "${name}" was not found. Existing environments: ${known}. Add one with "slskit env add ${name}".`);
+    }
+    return config;
+}
+// Resource names are derived, never stored, so renaming an environment can never
+// leave a stale name behind in the manifest.
+function stackNameFor(projectName, environment) {
+    return sanitizeName(`${projectName}-${environment}`);
+}
+function functionNameFor(projectName, environment, functionName) {
+    return sanitizeName(`${projectName}-${environment}-${functionName}`);
+}
+function sanitizeName(value) {
+    const cleaned = value
+        .replace(/[^A-Za-z0-9-]/g, "-")
+        .replace(/-{2,}/g, "-")
+        .replace(/^-+/, "")
+        .replace(/-+$/, "");
+    return /^[A-Za-z]/.test(cleaned) ? cleaned : `app-${cleaned}`;
+}
+// Checked at generate time so a too-long name fails while it is still a local
+// file, rather than midway through a CloudFormation deploy.
+function assertFunctionNameFits(projectName, environment, functionName) {
+    const full = functionNameFor(projectName, environment, functionName);
+    if (full.length > exports.FUNCTION_NAME_MAX) {
+        throw new errors_js_1.CliError(`Lambda function name "${full}" is ${full.length} characters, over the ${exports.FUNCTION_NAME_MAX} character limit.\nShorten the project name, the environment name "${environment}", or the function name "${functionName}".`);
+    }
+}
+function envVarSource(def) {
+    if (def.ssm) {
+        return "ssm";
+    }
+    if (def.secret) {
+        return "secret";
+    }
+    return "value";
+}
+// Templates are shared by every environment, so they declare a parameter for the
+// union of variable names. APP_ENVIRONMENT is excluded: it has its own dedicated
+// parameter and is never stored as a normal variable.
+function allEnvKeys(manifest) {
+    const keys = new Set();
+    for (const environment of Object.values(manifest.environments?.list ?? {})) {
+        for (const key of Object.keys(environment.variables ?? {})) {
+            if (key !== exports.APP_ENVIRONMENT_KEY) {
+                keys.add(key);
+            }
+        }
+    }
+    return [...keys].sort();
+}
+function writeEnvironment(cwd, manifest, name, config) {
+    const environments = manifest.environments;
+    writeManifest(cwd, {
+        ...manifest,
+        environments: {
+            default: environments?.default ?? name,
+            list: { ...environments?.list, [name]: config },
+        },
+    });
+}

package/dist/core/errors.d.ts

@@ -0,0 +1,4 @@
+export declare class CliError extends Error {
+    readonly exitCode: number;
+    constructor(message: string, exitCode?: number);
+}

package/dist/core/errors.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CliError = void 0;
+class CliError extends Error {
+    constructor(message, exitCode = 1) {
+        super(message);
+        this.name = "CliError";
+        this.exitCode = exitCode;
+    }
+}
+exports.CliError = CliError;

package/dist/core/flags-docs.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from "commander";
+export declare function generateFlagsMarkdown(program: Command): string;

package/dist/core/flags-docs.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.generateFlagsMarkdown = generateFlagsMarkdown;
+const GLOBAL_LONG = new Set(["--cwd", "--debug", "--silent", "--json", "--version"]);
+const HEADER = `# slskit — generated flag reference
+
+This file is generated from the Commander program. Do not edit it by hand.
+
+\`\`\`bash
+npm run docs
+\`\`\`
+
+CI fails if this file is stale. Narrative docs live in [COMMAND.md](../COMMAND.md).
+
+`;
+function optionLine(option) {
+    const def = option.defaultValue === undefined || option.defaultValue === false
+        ? ""
+        : ` (default: \`${String(option.defaultValue)}\`)`;
+    return `- \`${option.flags}\` — ${option.description ?? ""}${def}`;
+}
+function walk(command, trail) {
+    const name = [...trail, command.name()].filter(Boolean).join(" ");
+    const sections = [];
+    if (trail.length > 0 || command.name() !== "slskit") {
+        const args = command.registeredArguments ?? [];
+        const argText = args
+            .map((argument) => (argument.required ? `<${argument.name()}>` : `[${argument.name()}]`))
+            .join(" ");
+        const heading = argText ? `${name} ${argText}` : name;
+        sections.push(`## \`${heading}\``, "");
+        if (command.description()) {
+            sections.push(command.description(), "");
+        }
+        const options = command.options.filter((option) => !option.hidden && !GLOBAL_LONG.has(option.long ?? ""));
+        if (options.length > 0) {
+            sections.push("Flags:", "");
+            for (const option of options) {
+                sections.push(optionLine(option));
+            }
+            sections.push("");
+        }
+    }
+    for (const child of command.commands) {
+        const nextTrail = [...trail, command.name() === "slskit" ? "" : command.name()].filter(Boolean);
+        sections.push(...walk(child, nextTrail));
+    }
+    return sections;
+}
+function generateFlagsMarkdown(program) {
+    const globals = program.options.filter((option) => !option.hidden);
+    const parts = [
+        HEADER,
+        "## Global flags",
+        "",
+        "Available on every command.",
+        "",
+        ...globals.map(optionLine),
+        "",
+        ...walk(program, []),
+    ];
+    return `${parts.join("\n").replace(/\n{3,}/g, "\n\n").trim()}\n`;
+}

package/dist/core/is-ci.d.ts

@@ -0,0 +1,4 @@
+export declare function isCI(env?: NodeJS.ProcessEnv): boolean;
+export declare function isInteractive(stdin?: {
+    isTTY?: boolean;
+}, env?: NodeJS.ProcessEnv): boolean;

package/dist/core/is-ci.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isCI = isCI;
+exports.isInteractive = isInteractive;
+// Detects hosted CI without a dependency. `CI` is the de-facto signal; GitHub
+// Actions is listed explicitly because some self-hosted runners omit `CI`.
+function isCI(env = process.env) {
+    const ci = env.CI;
+    if (ci === "true" || ci === "1") {
+        return true;
+    }
+    return env.GITHUB_ACTIONS === "true";
+}
+function isInteractive(stdin = process.stdin, env = process.env) {
+    return Boolean(stdin.isTTY) && !isCI(env);
+}

package/dist/core/logger.d.ts

@@ -0,0 +1,4 @@
+export declare const logger: {
+    info(message: string): void;
+    error(message: string): void;
+};

package/dist/core/logger.js

@@ -0,0 +1,19 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = void 0;
+const context_js_1 = require("./context.js");
+function shouldWriteInfo() {
+    const { silent, json } = (0, context_js_1.getContext)();
+    return !silent && !json;
+}
+exports.logger = {
+    info(message) {
+        if (!shouldWriteInfo()) {
+            return;
+        }
+        process.stdout.write(`${message}\n`);
+    },
+    error(message) {
+        process.stderr.write(`${message}\n`);
+    },
+};

package/dist/core/run.d.ts

@@ -0,0 +1 @@
+export declare function runCommand(action: () => Promise<void> | void): Promise<void>;

package/dist/core/run.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runCommand = runCommand;
+const context_js_1 = require("./context.js");
+const errors_js_1 = require("./errors.js");
+const logger_js_1 = require("./logger.js");
+async function runCommand(action) {
+    try {
+        await action();
+    }
+    catch (error) {
+        if (error instanceof errors_js_1.CliError) {
+            logger_js_1.logger.error(error.message);
+            if ((0, context_js_1.getContext)().debug && error.stack) {
+                logger_js_1.logger.error(error.stack);
+            }
+            process.exitCode = error.exitCode;
+            return;
+        }
+        const message = error instanceof Error ? error.message : "Unexpected CLI error";
+        logger_js_1.logger.error(message);
+        if ((0, context_js_1.getContext)().debug && error instanceof Error && error.stack) {
+            logger_js_1.logger.error(error.stack);
+        }
+        process.exitCode = 1;
+    }
+}

package/dist/core/scope.d.ts

@@ -0,0 +1,33 @@
+import type { ProjectManifest } from "./environments.js";
+export interface ApplicationView {
+    name: string;
+    functions?: {
+        name: string;
+    }[];
+}
+export type ScopeKind = "all" | "service" | "function";
+export type Scope = {
+    kind: "all";
+    label: string;
+} | {
+    kind: "service";
+    label: string;
+    service: string;
+} | {
+    kind: "function";
+    label: string;
+    service: string;
+    functionName: string;
+};
+export declare const allScope: Scope;
+export declare function applicationsOf(manifest: ProjectManifest): ApplicationView[];
+export declare function requireService(manifest: ProjectManifest, name: string): ApplicationView;
+export declare function serviceScope(manifest: ProjectManifest, name: string): Scope;
+export declare function functionScope(manifest: ProjectManifest, name: string): Scope;
+export interface ScopeOptions {
+    service?: string;
+    function?: string;
+    all?: boolean;
+}
+export declare function scopeFromFlags(manifest: ProjectManifest, options: ScopeOptions): Scope | undefined;
+export declare function promptForScope(manifest: ProjectManifest, verb: string, everything: string): Promise<Scope>;

package/dist/core/scope.js

@@ -0,0 +1,108 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.allScope = void 0;
+exports.applicationsOf = applicationsOf;
+exports.requireService = requireService;
+exports.serviceScope = serviceScope;
+exports.functionScope = functionScope;
+exports.scopeFromFlags = scopeFromFlags;
+exports.promptForScope = promptForScope;
+const errors_js_1 = require("./errors.js");
+exports.allScope = { kind: "all", label: "the whole project" };
+function applicationsOf(manifest) {
+    return manifest.applications ?? [];
+}
+function requireService(manifest, name) {
+    const apps = applicationsOf(manifest);
+    const found = apps.find((app) => app.name === name);
+    if (!found) {
+        const known = apps.map((app) => app.name).join(", ") || "(none)";
+        throw new errors_js_1.CliError(`Service "${name}" was not found. This project has: ${known}.`);
+    }
+    return found;
+}
+function serviceScope(manifest, name) {
+    const app = requireService(manifest, name);
+    const count = (app.functions ?? []).length;
+    if (count === 0) {
+        throw new errors_js_1.CliError(`Service "${name}" has no functions.`);
+    }
+    return {
+        kind: "service",
+        label: `service "${name}" (${count} function${count === 1 ? "" : "s"})`,
+        service: name,
+    };
+}
+// Function names are unique across a project, so the service is derived rather than
+// asked for a second time.
+function functionScope(manifest, name) {
+    for (const app of applicationsOf(manifest)) {
+        for (const fn of app.functions ?? []) {
+            if (fn.name === name) {
+                return {
+                    kind: "function",
+                    label: `function "${app.name}/${fn.name}"`,
+                    service: app.name,
+                    functionName: fn.name,
+                };
+            }
+        }
+    }
+    const known = applicationsOf(manifest)
+        .flatMap((app) => (app.functions ?? []).map((fn) => fn.name))
+        .join(", ");
+    throw new errors_js_1.CliError(`Function "${name}" was not found. This project has: ${known || "(none)"}.`);
+}
+function scopeFromFlags(manifest, options) {
+    if (options.service && options.function) {
+        throw new errors_js_1.CliError('Pass either "--service" or "--function", not both.');
+    }
+    if (options.service) {
+        return serviceScope(manifest, options.service);
+    }
+    if (options.function) {
+        return functionScope(manifest, options.function);
+    }
+    return options.all ? exports.allScope : undefined;
+}
+// Asks what to act on, then which one. Only reached with a TTY and no scope flag.
+async function promptForScope(manifest, verb, everything) {
+    const apps = applicationsOf(manifest).filter((app) => (app.functions ?? []).length > 0);
+    if (apps.length === 0) {
+        return exports.allScope;
+    }
+    const { select } = await import("@inquirer/prompts");
+    const kind = await select({
+        message: `What do you want to ${verb}?`,
+        choices: [
+            { name: everything, value: "all" },
+            { name: "One service — all of its functions", value: "service" },
+            { name: "One function", value: "function" },
+        ],
+    });
+    if (kind === "all") {
+        return exports.allScope;
+    }
+    if (kind === "service") {
+        const name = await select({
+            message: "Service:",
+            choices: apps.map((app) => ({
+                name: `${app.name} (${(app.functions ?? []).length} functions)`,
+                value: app.name,
+            })),
+        });
+        return serviceScope(manifest, name);
+    }
+    const service = await select({
+        message: "Service:",
+        choices: apps.map((app) => ({ name: app.name, value: app.name })),
+    });
+    const functionName = await select({
+        message: "Function:",
+        choices: (requireService(manifest, service).functions ?? []).map((fn) => ({
+            name: fn.name,
+            value: fn.name,
+        })),
+    });
+    return functionScope(manifest, functionName);
+}

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+export { createProgram } from "./program.js";
+export { CliError } from "./core/errors.js";
+export { logger } from "./core/logger.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.logger = exports.CliError = exports.createProgram = void 0;
+var program_js_1 = require("./program.js");
+Object.defineProperty(exports, "createProgram", { enumerable: true, get: function () { return program_js_1.createProgram; } });
+var errors_js_1 = require("./core/errors.js");
+Object.defineProperty(exports, "CliError", { enumerable: true, get: function () { return errors_js_1.CliError; } });
+var logger_js_1 = require("./core/logger.js");
+Object.defineProperty(exports, "logger", { enumerable: true, get: function () { return logger_js_1.logger; } });

package/dist/program.d.ts

@@ -0,0 +1,2 @@
+import { BaseCommand } from "./commands/base-command.js";
+export declare function createProgram(): BaseCommand;

package/dist/program.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createProgram = createProgram;
+const base_command_js_1 = require("./commands/base-command.js");
+const index_js_1 = require("./commands/index.js");
+// Read at runtime rather than hardcoded, so "slskit --version" can never drift from
+// what was actually published. Resolves to the package root from both dist/ and src/,
+// which is why running from source via tsx reports the same number.
+function packageVersion() {
+    try {
+        return require("../package.json").version;
+    }
+    catch {
+        return "0.0.0";
+    }
+}
+function createProgram() {
+    const program = new base_command_js_1.BaseCommand();
+    program
+        .name("slskit")
+        .description("Scaffold and incrementally grow multi-service AWS Lambda projects")
+        .version(packageVersion());
+    (0, base_command_js_1.addGlobalOptions)(program);
+    (0, index_js_1.registerCommands)(program);
+    return program;
+}

package/package.json

@@ -0,0 +1,110 @@
+{
+  "name": "slskit-cli",
+  "version": "1.0.0",
+  "description": "Scaffold and grow multi-service AWS Lambda projects on AWS SAM — local runs with hot reload, isolated environments, and single-function deploys",
+  "keywords": [
+    "aws",
+    "aws-lambda",
+    "lambda",
+    "serverless",
+    "aws-sam",
+    "sam",
+    "sam-cli",
+    "cli",
+    "scaffold",
+    "generator",
+    "project-generator",
+    "boilerplate",
+    "starter",
+    "typescript",
+    "javascript",
+    "python",
+    "api-gateway",
+    "http-api",
+    "cloudformation",
+    "iac",
+    "infrastructure-as-code",
+    "lambda-layer",
+    "dynamodb",
+    "hot-reload",
+    "multi-service",
+    "deployment",
+    "developer-tools"
+  ],
+  "homepage": "https://github.com/savindaJ/SLSKIT-CLI#readme",
+  "bugs": {
+    "url": "https://github.com/savindaJ/SLSKIT-CLI/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/savindaJ/SLSKIT-CLI.git"
+  },
+  "license": "MIT",
+  "author": {
+    "name": "Savinda Jayasekara",
+    "url": "https://github.com/savindaJ"
+  },
+  "type": "commonjs",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "require": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "bin": {
+    "slskit": "bin/slskit.js"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "COMMAND.md",
+    "CHANGELOG.md",
+    "NOTICE.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc",
+    "build:release": "npm run clean && tsc -p tsconfig.build.json",
+    "changeset": "changeset",
+    "changeset:publish": "changeset publish",
+    "changeset:status": "changeset status --verbose",
+    "changeset:version": "changeset version",
+    "clean": "rm -rf dist",
+    "dev": "tsx src/cli.ts",
+    "docs": "tsx scripts/generate-docs.ts",
+    "docs:check": "tsx scripts/generate-docs.ts --check",
+    "licenses": "node scripts/check-licenses.js",
+    "lint": "tsc --noEmit",
+    "prepublishOnly": "npm run clean && npm run typecheck && npm run licenses && npm test && npm run build:release",
+    "start": "node bin/slskit.js",
+    "test": "jest",
+    "test:cli": "jest test/cli",
+    "test:unit": "jest test/unit",
+    "test:watch": "jest --watch",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@inquirer/prompts": "^8.5.2",
+    "commander": "^12.1.0"
+  },
+  "devDependencies": {
+    "@changesets/cli": "^2.31.1",
+    "@types/jest": "^30.0.0",
+    "@types/node": "^22.10.2",
+    "jest": "^30.4.2",
+    "pkg-pr-new": "^0.0.88",
+    "ts-jest": "^29.4.12",
+    "tsx": "^4.19.2",
+    "typescript": "^5.7.2"
+  }
+}