slskit-cli 1.0.0

package/dist/commands/run/resources.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resourceIdFor = resourceIdFor;
+exports.classifyChange = classifyChange;
+exports.planRebuild = planRebuild;
+const helpers_js_1 = require("../init/templates/helpers.js");
+// Per-service stacks put every function behind its application's stack, so the id sam
+// build wants is the two joined. One shared API Gateway means a single flat template
+// instead, where the function is addressed on its own.
+function resourceIdFor(appName, functionName, sharedApi = false) {
+    const fn = `${(0, helpers_js_1.pascal)(functionName)}Function`;
+    return sharedApi ? fn : `${(0, helpers_js_1.pascal)(appName)}Stack/${fn}`;
+}
+function findFunction(applications, appName, functionName) {
+    return (applications.find((app) => app.name === appName)?.functions ?? []).some((fn) => fn.name === functionName);
+}
+// A service module is imported by the handler of the same name, which is the shape
+// every generated project has. Anything that does not match that 1:1 convention
+// falls back to a full build rather than guessing which functions import it.
+function fromService(applications, segments, sharedApi) {
+    if (segments.length !== 2) {
+        return undefined;
+    }
+    const [appName, file] = segments;
+    const functionName = file.replace(/\.[^.]+$/, "");
+    if (!findFunction(applications, appName, functionName)) {
+        return undefined;
+    }
+    return {
+        kind: "function",
+        resourceId: resourceIdFor(appName, functionName, sharedApi),
+        label: `${appName}/${functionName}`,
+    };
+}
+function fromHandler(applications, segments, sharedApi) {
+    if (segments.length < 2) {
+        return undefined;
+    }
+    const [appName, functionName] = segments;
+    if (!findFunction(applications, appName, functionName)) {
+        return undefined;
+    }
+    return {
+        kind: "function",
+        resourceId: resourceIdFor(appName, functionName, sharedApi),
+        label: `${appName}/${functionName}`,
+    };
+}
+function normalizeRelativePath(relativePath) {
+    return relativePath.replace(/\\/g, "/");
+}
+function classifyChange(applications, relativePath, sharedApi = false) {
+    const normalizedPath = normalizeRelativePath(relativePath);
+    const segments = normalizedPath.split("/").filter(Boolean);
+    const base = segments[segments.length - 1] ?? normalizedPath;
+    // Routes, memory, layers and parameter values are all read when sam starts.
+    // Service templates live in templates/ and are named after their service, so it is
+    // the directory that identifies them rather than the filename.
+    const isTemplate = base === "template.yaml" ||
+        (segments[0] === "templates" && /\.ya?ml$/.test(base));
+    if (isTemplate || base === "slskit.json" || base.startsWith(".env")) {
+        return { kind: "restart", label: base };
+    }
+    if (segments[0] !== "src") {
+        return { kind: "full", label: normalizedPath };
+    }
+    const area = segments[1];
+    const rest = segments.slice(2);
+    if (area === "functions") {
+        return (fromHandler(applications, rest, sharedApi) ?? { kind: "full", label: normalizedPath });
+    }
+    if (area === "services") {
+        return (fromService(applications, rest, sharedApi) ?? { kind: "full", label: normalizedPath });
+    }
+    // src/shared is published as a layer attached to every function in every stack.
+    return { kind: "full", label: normalizedPath };
+}
+// One decision for a whole batch of file events: the most disruptive change wins,
+// and a batch of ordinary edits collapses to the set of functions to rebuild.
+function planRebuild(changes) {
+    const labels = [...new Set(changes.map((change) => change.label))];
+    if (changes.some((change) => change.kind === "restart")) {
+        return { kind: "restart", resourceIds: [], labels };
+    }
+    if (changes.some((change) => change.kind === "full")) {
+        return { kind: "full", resourceIds: [], labels };
+    }
+    return {
+        kind: "function",
+        resourceIds: [...new Set(changes.map((change) => change.resourceId))],
+        labels,
+    };
+}

package/dist/commands/run/sam-cli.d.ts

@@ -0,0 +1,10 @@
+import type { ChildProcess } from "node:child_process";
+export declare function ensureSamCliInstalled(): Promise<void>;
+export interface BuildTarget {
+    template?: string;
+    buildDir?: string;
+}
+export declare function samBuild(cwd: string, target?: BuildTarget): void;
+export declare function samBuildResource(cwd: string, resourceId: string, target?: BuildTarget): boolean;
+export declare function samRebuild(cwd: string, target?: BuildTarget): boolean;
+export declare function startLocalApi(cwd: string, port: number, parameterOverrides?: string[], template?: string): ChildProcess;

package/dist/commands/run/sam-cli.js

@@ -0,0 +1,183 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ensureSamCliInstalled = ensureSamCliInstalled;
+exports.samBuild = samBuild;
+exports.samBuildResource = samBuildResource;
+exports.samRebuild = samRebuild;
+exports.startLocalApi = startLocalApi;
+const node_child_process_1 = require("node:child_process");
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("../../core/errors.js");
+const logger_js_1 = require("../../core/logger.js");
+const USE_SHELL = process.platform === "win32";
+const GUIDE_URLS = {
+    darwin: "https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli-mac.html",
+    linux: "https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli-linux.html",
+    win32: "https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli-windows.html",
+};
+const GENERAL_GUIDE_URL = "https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/install-sam-cli.html";
+function platformGuideUrl() {
+    return GUIDE_URLS[process.platform] ?? GENERAL_GUIDE_URL;
+}
+function printManualGuide() {
+    logger_js_1.logger.info(`\nInstall AWS SAM CLI manually, then re-run "slskit run":\n  ${platformGuideUrl()}\n\nVerify the install with: sam --version\n`);
+}
+function commandExists(command) {
+    const result = (0, node_child_process_1.spawnSync)(command, ["--version"], {
+        stdio: "ignore",
+        shell: USE_SHELL,
+    });
+    return !result.error;
+}
+function isSamCliAvailable() {
+    const result = (0, node_child_process_1.spawnSync)("sam", ["--version"], {
+        stdio: "ignore",
+        shell: USE_SHELL,
+    });
+    return !result.error && result.status === 0;
+}
+function installViaBrew() {
+    if (!commandExists("brew")) {
+        logger_js_1.logger.info("Homebrew was not found (https://brew.sh). Falling back to a manual install.");
+        return false;
+    }
+    logger_js_1.logger.info("\n> brew install aws/tap/aws-sam-cli");
+    const result = (0, node_child_process_1.spawnSync)("brew", ["install", "aws/tap/aws-sam-cli"], {
+        stdio: "inherit",
+    });
+    return !result.error && result.status === 0;
+}
+function installViaSnap() {
+    if (!commandExists("snap")) {
+        logger_js_1.logger.info("snap was not found. Falling back to a manual install.");
+        return false;
+    }
+    logger_js_1.logger.info("\n> sudo snap install aws-sam-cli --classic");
+    const result = (0, node_child_process_1.spawnSync)("sudo", ["snap", "install", "aws-sam-cli", "--classic"], {
+        stdio: "inherit",
+    });
+    return !result.error && result.status === 0;
+}
+function attemptInstall() {
+    if (process.platform === "darwin") {
+        return installViaBrew();
+    }
+    if (process.platform === "linux") {
+        return installViaSnap();
+    }
+    logger_js_1.logger.info(`Automatic install isn't available on "${process.platform}".`);
+    return false;
+}
+async function ensureSamCliInstalled() {
+    if (isSamCliAvailable()) {
+        return;
+    }
+    logger_js_1.logger.info("AWS SAM CLI was not found on your PATH.");
+    if (!process.stdin.isTTY) {
+        printManualGuide();
+        throw new errors_js_1.CliError("AWS SAM CLI is required to run this project locally.");
+    }
+    const { confirm } = await import("@inquirer/prompts");
+    const shouldInstall = await confirm({
+        message: "Install AWS SAM CLI now?",
+        default: true,
+    });
+    if (!shouldInstall) {
+        printManualGuide();
+        throw new errors_js_1.CliError("AWS SAM CLI is required to run this project locally.");
+    }
+    const installed = attemptInstall() && isSamCliAvailable();
+    if (!installed) {
+        printManualGuide();
+        throw new errors_js_1.CliError("AWS SAM CLI installation did not complete.");
+    }
+    logger_js_1.logger.info("\nAWS SAM CLI installed.\n");
+}
+function targetArgs(target) {
+    const args = [];
+    if (target.template) {
+        args.push("-t", target.template);
+    }
+    if (target.buildDir) {
+        args.push("--build-dir", target.buildDir);
+    }
+    return args;
+}
+function samBuild(cwd, target = {}) {
+    const args = ["build", ...targetArgs(target)];
+    logger_js_1.logger.info(`\n> sam ${args.join(" ")}`);
+    const result = (0, node_child_process_1.spawnSync)("sam", args, {
+        cwd,
+        stdio: "inherit",
+        shell: USE_SHELL,
+    });
+    if (result.error) {
+        throw new errors_js_1.CliError(`Failed to run sam build: ${result.error.message}`);
+    }
+    if (result.status !== 0) {
+        throw new errors_js_1.CliError(`sam build exited with code ${result.status ?? 1}`);
+    }
+}
+const PARTIAL_BUILD_DIR = node_path_1.default.join(".aws-sam", "slskit-partial");
+// "sam build <ResourceId>" empties the whole build directory and puts back only the
+// resource it was asked for, which would leave every other function unservable. So
+// the scoped build goes to a scratch directory and just that one artifact is moved
+// into place -- the running local API picks it up on the next request.
+function samBuildResource(cwd, resourceId, target = {}) {
+    const scratch = node_path_1.default.join(cwd, PARTIAL_BUILD_DIR);
+    node_fs_1.default.rmSync(scratch, { recursive: true, force: true });
+    const args = ["build", resourceId, "--build-dir", PARTIAL_BUILD_DIR];
+    if (target.template) {
+        args.push("-t", target.template);
+    }
+    const result = (0, node_child_process_1.spawnSync)("sam", args, {
+        cwd,
+        stdio: "inherit",
+        shell: USE_SHELL,
+    });
+    if (result.error || result.status !== 0) {
+        node_fs_1.default.rmSync(scratch, { recursive: true, force: true });
+        return false;
+    }
+    const built = node_path_1.default.join(scratch, resourceId);
+    const destination = node_path_1.default.join(cwd, target.buildDir ?? node_path_1.default.join(".aws-sam", "build"), resourceId);
+    if (!node_fs_1.default.existsSync(built)) {
+        node_fs_1.default.rmSync(scratch, { recursive: true, force: true });
+        return false;
+    }
+    node_fs_1.default.rmSync(destination, { recursive: true, force: true });
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(destination), { recursive: true });
+    node_fs_1.default.renameSync(built, destination);
+    node_fs_1.default.rmSync(scratch, { recursive: true, force: true });
+    return true;
+}
+// Unlike samBuild this never throws: a syntax error in a handler must not tear down
+// a watch session that the next save would fix.
+function samRebuild(cwd, target = {}) {
+    const result = (0, node_child_process_1.spawnSync)("sam", ["build", ...targetArgs(target)], {
+        cwd,
+        stdio: "inherit",
+        shell: USE_SHELL,
+    });
+    return !result.error && result.status === 0;
+}
+function startLocalApi(cwd, port, parameterOverrides = [], template) {
+    const overrideArgs = parameterOverrides.length > 0
+        ? ["--parameter-overrides", ...parameterOverrides]
+        : [];
+    // Values are deliberately not logged: overrides carry secrets.
+    const overrideNote = parameterOverrides.length > 0
+        ? ` --parameter-overrides (${parameterOverrides.length} value${parameterOverrides.length === 1 ? "" : "s"})`
+        : "";
+    const templateArgs = template ? ["-t", template] : [];
+    logger_js_1.logger.info(`\n> sam local start-api --port ${port}${overrideNote}`);
+    const child = (0, node_child_process_1.spawn)("sam", ["local", "start-api", "--port", String(port), ...templateArgs, ...overrideArgs], { cwd, stdio: "inherit", shell: USE_SHELL });
+    child.on("error", (error) => {
+        logger_js_1.logger.error(`Failed to run sam local start-api: ${error.message}`);
+    });
+    return child;
+}

package/dist/commands/run/types.d.ts

@@ -0,0 +1,18 @@
+export interface RunOptions {
+    /** Run every function in one service. */
+    service?: string;
+    /** Run one function on its own. */
+    function?: string;
+    /** Skip the scope prompt and run everything. */
+    all?: boolean;
+    port?: string | number;
+    build?: boolean;
+    env?: string;
+    watch?: boolean;
+}
+export interface ProjectManifestFile {
+    name: string;
+    framework: {
+        id: string;
+    };
+}

package/dist/commands/run/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/dist/commands/run/watch.d.ts

@@ -0,0 +1,11 @@
+import type { ApplicationView } from "./resources.js";
+export interface WatchHandlers {
+    onFunctions: (resourceIds: string[], labels: string[]) => void;
+    onFull: (labels: string[]) => void;
+    onRestart: (labels: string[]) => void;
+}
+export interface Watcher {
+    close: () => void;
+}
+export declare function watchProject(cwd: string, applications: ApplicationView[], handlers: WatchHandlers, sharedApi?: boolean): Watcher;
+export declare function describeChange(labels: string[]): string;

package/dist/commands/run/watch.js

@@ -0,0 +1,131 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.watchProject = watchProject;
+exports.describeChange = describeChange;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const resources_js_1 = require("./resources.js");
+// Editors save in bursts -- a write, a rename, sometimes a companion file -- so
+// events are collected for a moment and acted on once.
+const DEBOUNCE_MS = 200;
+const IGNORED_DIRS = new Set([".aws-sam", "node_modules", "dist", ".git", ".venv"]);
+const WATCHED_EXTENSIONS = new Set([".ts", ".js", ".mjs", ".cjs", ".py", ".json", ".yaml", ".yml"]);
+// Editors write temporary siblings while saving; acting on those would rebuild twice.
+function isRelevant(relativePath) {
+    const base = node_path_1.default.basename(relativePath);
+    if (base.startsWith(".") && !base.startsWith(".env")) {
+        return false;
+    }
+    if (base.startsWith(".env")) {
+        return true;
+    }
+    if (base.endsWith("~") || base.endsWith(".swp") || base.endsWith(".tmp")) {
+        return false;
+    }
+    return WATCHED_EXTENSIONS.has(node_path_1.default.extname(base));
+}
+function directoriesUnder(root) {
+    const found = [];
+    const walk = (dir) => {
+        found.push(dir);
+        let entries;
+        try {
+            entries = node_fs_1.default.readdirSync(dir, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory() && !IGNORED_DIRS.has(entry.name)) {
+                walk(node_path_1.default.join(dir, entry.name));
+            }
+        }
+    };
+    walk(root);
+    return found;
+}
+// Watches the project's sources plus the files that decide how sam is started, and
+// hands each debounced batch to the caller as one decision.
+function watchProject(cwd, applications, handlers, sharedApi = false) {
+    const watchers = [];
+    const batch = [];
+    let timer;
+    let closed = false;
+    const flush = () => {
+        timer = undefined;
+        if (closed || batch.length === 0) {
+            return;
+        }
+        const plan = (0, resources_js_1.planRebuild)(batch.splice(0, batch.length));
+        if (plan.kind === "restart") {
+            handlers.onRestart(plan.labels);
+            return;
+        }
+        if (plan.kind === "full") {
+            handlers.onFull(plan.labels);
+            return;
+        }
+        handlers.onFunctions(plan.resourceIds, plan.labels);
+    };
+    const record = (relativePath) => {
+        if (closed || !isRelevant(relativePath)) {
+            return;
+        }
+        batch.push((0, resources_js_1.classifyChange)(applications, relativePath, sharedApi));
+        if (timer) {
+            clearTimeout(timer);
+        }
+        timer = setTimeout(flush, DEBOUNCE_MS);
+    };
+    const watchDir = (dir, recursive) => {
+        try {
+            const watcher = node_fs_1.default.watch(dir, { recursive }, (_event, filename) => {
+                if (!filename) {
+                    return;
+                }
+                record(node_path_1.default.relative(cwd, node_path_1.default.join(dir, filename.toString())));
+            });
+            watchers.push(watcher);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    };
+    for (const name of ["src", "templates"]) {
+        const dir = node_path_1.default.join(cwd, name);
+        if (!node_fs_1.default.existsSync(dir)) {
+            continue;
+        }
+        // Recursive watching is not available on every platform, so each directory is
+        // watched individually when it is not.
+        if (!watchDir(dir, true)) {
+            for (const child of directoriesUnder(dir)) {
+                watchDir(child, false);
+            }
+        }
+    }
+    // The project root itself, for template.yaml, slskit.json and the .env files. Not
+    // recursive: everything below it that matters is already covered above.
+    watchDir(cwd, false);
+    return {
+        close: () => {
+            closed = true;
+            if (timer) {
+                clearTimeout(timer);
+            }
+            for (const watcher of watchers) {
+                watcher.close();
+            }
+        },
+    };
+}
+function describeChange(labels) {
+    if (labels.length <= 2) {
+        return labels.join(", ");
+    }
+    return `${labels.slice(0, 2).join(", ")} and ${labels.length - 2} more`;
+}

package/dist/core/context.d.ts

@@ -0,0 +1,15 @@
+export interface GlobalOptions {
+    cwd?: string;
+    debug?: boolean;
+    silent?: boolean;
+    json?: boolean;
+}
+export interface CliContext {
+    cwd: string;
+    debug: boolean;
+    silent: boolean;
+    json: boolean;
+}
+export declare function getContext(): CliContext;
+export declare function resetContext(): void;
+export declare function applyGlobalOptions(options: GlobalOptions): void;

package/dist/core/context.js

@@ -0,0 +1,41 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getContext = getContext;
+exports.resetContext = resetContext;
+exports.applyGlobalOptions = applyGlobalOptions;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const errors_js_1 = require("./errors.js");
+function defaultContext() {
+    return {
+        cwd: process.cwd(),
+        debug: false,
+        silent: false,
+        json: false,
+    };
+}
+let context = defaultContext();
+function getContext() {
+    return context;
+}
+function resetContext() {
+    context = defaultContext();
+}
+function applyGlobalOptions(options) {
+    if (options.cwd) {
+        const resolved = node_path_1.default.resolve(options.cwd);
+        if (!node_fs_1.default.existsSync(resolved) || !node_fs_1.default.statSync(resolved).isDirectory()) {
+            throw new errors_js_1.CliError(`Working directory "${options.cwd}" does not exist.`);
+        }
+        process.chdir(resolved);
+    }
+    context = {
+        cwd: process.cwd(),
+        debug: Boolean(options.debug),
+        silent: Boolean(options.silent),
+        json: Boolean(options.json),
+    };
+}

package/dist/core/credentials.d.ts

@@ -0,0 +1,10 @@
+export type ProfileSource = "flag" | "config" | "env" | "none";
+export interface ResolvedProfile {
+    profile: string | undefined;
+    source: ProfileSource;
+}
+export declare function resolveAwsProfile(options: {
+    flag?: string;
+    stored?: string;
+    env?: NodeJS.ProcessEnv;
+}): ResolvedProfile;

package/dist/core/credentials.js

@@ -0,0 +1,22 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAwsProfile = resolveAwsProfile;
+// Resolution order is conservative on purpose: a leftover AWS_PROFILE in the
+// shell must not override the profile this project stored in slskit.json.
+// An explicit --profile always wins.
+function resolveAwsProfile(options) {
+    const env = options.env ?? process.env;
+    const fromFlag = options.flag?.trim();
+    if (fromFlag) {
+        return { profile: fromFlag, source: "flag" };
+    }
+    const fromStore = options.stored?.trim();
+    if (fromStore) {
+        return { profile: fromStore, source: "config" };
+    }
+    const fromEnv = env.AWS_PROFILE?.trim();
+    if (fromEnv) {
+        return { profile: fromEnv, source: "env" };
+    }
+    return { profile: undefined, source: "none" };
+}

package/dist/core/environments.d.ts

@@ -0,0 +1,46 @@
+export declare const MANIFEST_FILE = "slskit.json";
+export declare const LEGACY_MANIFEST_FILE = "sless.json";
+export declare function manifestPathFor(cwd: string): string | undefined;
+export declare const DEFAULT_ENVIRONMENT = "dev";
+export declare const APP_ENVIRONMENT_KEY = "APP_ENVIRONMENT";
+export declare const APP_ENVIRONMENT_PARAM = "AppEnvironment";
+export declare const FUNCTION_NAME_MAX = 64;
+export interface EnvVarDef {
+    value?: string;
+    secret?: boolean;
+    ssm?: string;
+}
+export type EnvVarSource = "value" | "secret" | "ssm";
+export interface EnvironmentConfig {
+    region?: string;
+    profile?: string;
+    stackName: string;
+    variables?: Record<string, EnvVarDef>;
+}
+export interface EnvironmentsConfig {
+    default: string;
+    list: Record<string, EnvironmentConfig>;
+}
+export interface ProjectManifest {
+    name: string;
+    framework?: {
+        id?: string;
+    };
+    environments?: EnvironmentsConfig;
+    [key: string]: unknown;
+}
+export declare function readManifest(cwd: string, command?: string): ProjectManifest;
+export declare function writeManifest(cwd: string, manifest: ProjectManifest): void;
+export declare function parseEnvironmentName(value: string | undefined, label?: string): string | undefined;
+export declare function environmentNames(manifest: ProjectManifest): string[];
+export declare function defaultEnvironment(manifest: ProjectManifest): string;
+export declare function resolveEnvironmentName(manifest: ProjectManifest, requested?: string): string;
+export declare function requireEnvironment(manifest: ProjectManifest, name: string): EnvironmentConfig;
+export declare function stackNameFor(projectName: string, environment: string): string;
+export declare function functionNameFor(projectName: string, environment: string, functionName: string): string;
+export declare function assertFunctionNameFits(projectName: string, environment: string, functionName: string): void;
+export declare function envVarSource(def: EnvVarDef): EnvVarSource;
+export declare function allEnvKeys(manifest: {
+    environments?: EnvironmentsConfig;
+}): string[];
+export declare function writeEnvironment(cwd: string, manifest: ProjectManifest, name: string, config: EnvironmentConfig): void;