@fastang/cli 0.0.0-stage → 0.1.0-alpha.3

package/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+## 0.1.0-alpha.3
+
+- Standalone lightweight `fastang` and `fastang-cli` commands.
+- Create projects with the matching generator release.
+- Plan and apply npm core updates, including apps using older framework versions.
+- Forward development, build, generation and route inspection to the local core.
+
+- Compare installed peers and Node before updates; block incompatible installs.
+- Skip identical versions and require explicit permission for downgrades.
+- Forward termination signals to local server processes.
+
+- Check manifest, lockfile and installed core consistency before applying updates.
+- Use one process runner for npm and local runtime commands.

package/LICENSE

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

@@ -1,3 +1,39 @@
-# Temporary Holding Version
+# @fastang/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Lightweight FastAng CLI. Available starting with `0.1.0-alpha.3`:
+
+```sh
+npm install -g @fastang/cli@alpha
+fastang new my-app --install
+cd my-app
+fastang dev
+fastang update --to alpha
+fastang update --to alpha --yes
+```
+
+Without a global install, use `npx --package=@fastang/cli@alpha fastang new my-app`.
+`new` uses the generator matching the CLI release. `dev`, `build`, `generate` and
+`routes` execute the app's installed core, preserving its version and arguments.
+No Angular, Vite or Fastify dependencies are installed with this CLI.
+Its only runtime dependency is semver for version comparisons.
+
+`update` also works with older cores: it runs in the standalone CLI and updates
+the app's core dependency. It defaults to a plan. `--yes` installs the resolved
+exact version with strict peer and Node engine checks. Source migrations remain
+manual; commit your app first, review the release instructions and run your tests.
+Use `--to latest` for the npm latest tag or `--to alpha` for the alpha channel.
+
+Inside npm scripts and with `npx fastang`, the app's local binary takes precedence.
+For an older project, explicitly select the standalone CLI without a bin conflict:
+
+```sh
+npx --package=@fastang/cli@alpha fastang-cli update --to alpha
+```
+
+The alias `fastang-cli` provides the same commands as `fastang`. Avoid installing
+this package alongside core as an app dependency; a global install or npm exec
+keeps the two executables separate.
+
+The plan compares installed versions and Node with target requirements. Applying
+is blocked on incompatibility. An identical installed version is a no-op;
+downgrades require `--allow-downgrade` explicitly. Source migrations remain manual.

package/bin/fastang.mjs

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+import { resolve } from 'node:path';
+import { ProcessError, runProcess } from '../dist/process.js';
+import { cliVersion, installedPackage, newProject, updateProject } from '../dist/commands/project.js';
+
+const [command, ...args] = process.argv.slice(2);
+try {
+  if (command === 'new') await newProject(args);
+  else if (command === 'update') await updateProject(args);
+  else if (command === '--version' || command === '-v') console.log(await cliVersion());
+  else if (!command || command === '--help' || command === '-h') {
+    console.log('Usage: fastang <new|update|dev|build|generate|routes>\n  new <directory> [--install]\n  update --to <version|tag> [--dry-run | --yes] [--allow-downgrade]\n  dev, build, generate, routes: use the core installed in your app');
+  } else if (['dev', 'build', 'generate', 'routes'].includes(command)) {
+    const pkg = await installedPackage('@fastang/core', process.cwd());
+    if (!pkg) throw new Error('No local @fastang/core found. Run this command inside an installed FastAng app.');
+    if (typeof pkg.manifest.bin?.fastang !== 'string') throw new Error('The local core has no fastang executable.');
+    const bin = resolve(pkg.directory, pkg.manifest.bin.fastang);
+    await runProcess(process.execPath, [bin, command, ...args]);
+  } else throw new Error(`Unknown command: ${command}`);
+} catch (error) {
+  console.error(`fastang: ${error instanceof Error ? error.message : error}`);
+  process.exitCode = error instanceof ProcessError ? error.code : 1;
+}

package/dist/commands/project.d.ts

@@ -0,0 +1,13 @@
+export type NpmRunner = (args: string[], capture?: boolean) => Promise<string>;
+export declare const runNpm: NpmRunner;
+export declare function cliVersion(): Promise<string>;
+export declare function newProject(args: string[], npm?: NpmRunner): Promise<void>;
+export declare function installedPackage(name: string, directory: string): Promise<{
+    directory: string;
+    manifest: Record<string, any>;
+} | undefined>;
+export declare function installedVersion(name: string, directory: string): Promise<string | undefined>;
+export declare function updateProject(args: string[], npm?: NpmRunner, directory?: string, log?: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+}): Promise<void>;

package/dist/commands/project.js

@@ -0,0 +1,140 @@
+import { readFile } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { lt, satisfies, valid, validRange } from 'semver';
+import { runProcess } from "../process.js";
+export const runNpm = async (args, capture = false) => {
+    const windows = process.platform === 'win32';
+    if (windows && args.some(arg => /[&|<>^%!"\r\n]/.test(arg)))
+        throw new Error('Unsupported shell characters in npm arguments on Windows.');
+    return runProcess(windows ? 'npm.cmd' : 'npm', windows ? args.map(arg => `"${arg}"`) : args, { capture, shell: windows });
+};
+export async function cliVersion() {
+    const manifest = JSON.parse(await readFile(new URL('../../package.json', import.meta.url), 'utf8'));
+    return manifest.version;
+}
+export async function newProject(args, npm = runNpm) {
+    // A release always uses its matching generator; existing destinations are rejected there.
+    await npm(['exec', '--yes', `--package=create-fastang@${await cliVersion()}`, '--', 'create-fastang', ...args]);
+}
+export async function installedPackage(name, directory) {
+    let current = resolve(directory);
+    while (true) {
+        const root = join(current, 'node_modules', name);
+        try {
+            const manifest = JSON.parse(await readFile(join(root, 'package.json'), 'utf8'));
+            if (manifest.name === name)
+                return { directory: root, manifest };
+        }
+        catch (error) {
+            if (error.code !== 'ENOENT')
+                throw error;
+        }
+        const parent = dirname(current);
+        if (parent === current)
+            return undefined;
+        current = parent;
+    }
+}
+export async function installedVersion(name, directory) {
+    const pkg = await installedPackage(name, directory);
+    return pkg && valid(pkg.manifest.version) ? pkg.manifest.version : undefined;
+}
+export async function updateProject(args, npm = runNpm, directory = process.cwd(), log = console.log) {
+    if (args.length === 1 && (args[0] === '--help' || args[0] === '-h')) {
+        log('Usage: fastang update --to <version|tag> [--dry-run | --yes] [--allow-downgrade]');
+        return;
+    }
+    let target;
+    let apply = false;
+    let dryRun = false;
+    let allowDowngrade = false;
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg === '--to' && !target)
+            target = args[++i];
+        else if (arg === '--allow-downgrade' && !allowDowngrade)
+            allowDowngrade = true;
+        else if (arg === '--yes' && !apply)
+            apply = true;
+        else if (arg === '--dry-run' && !dryRun)
+            dryRun = true;
+        else
+            throw new Error('Usage: fastang update --to <version|tag> [--dry-run | --yes] [--allow-downgrade]');
+    }
+    if (!target || !/^[a-zA-Z0-9][a-zA-Z0-9.+-]*$/.test(target) || (apply && dryRun)) {
+        throw new Error('Usage: fastang update --to <version|tag> [--dry-run | --yes] [--allow-downgrade]');
+    }
+    const project = JSON.parse(await readFile(resolve(directory, 'package.json'), 'utf8'));
+    if (project.workspaces)
+        throw new Error('Run update in an individual app, not a workspace root. Update workspace dependencies manually.');
+    if (project.packageManager && !project.packageManager.startsWith('npm@'))
+        throw new Error('fastang update currently supports npm projects only.');
+    const section = project.dependencies?.['@fastang/core'] ? 'dependencies' : project.devDependencies?.['@fastang/core'] ? 'devDependencies' : undefined;
+    if (!section)
+        throw new Error('This project does not declare @fastang/core. Run the command from your app directory.');
+    const response = JSON.parse(await npm(['view', `@fastang/core@${target}`, 'version', 'engines', 'peerDependencies', 'peerDependenciesMeta', '--json'], true));
+    const metadata = Array.isArray(response) && response.length === 1 ? response[0] : response;
+    if (!metadata || typeof metadata.version !== 'string' || !/^\d+\.\d+\.\d+(?:-[\da-zA-Z.-]+)?(?:\+[\da-zA-Z.-]+)?$/.test(metadata.version))
+        throw new Error('npm did not return a single release version.');
+    const current = await installedVersion('@fastang/core', directory);
+    const declared = project[section]['@fastang/core'];
+    const problems = [];
+    let lock;
+    try {
+        lock = JSON.parse(await readFile(resolve(directory, 'package-lock.json'), 'utf8'));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+        problems.push('package-lock.json is missing. Run npm install and review the lockfile first.');
+    }
+    const locked = lock?.packages?.['node_modules/@fastang/core']?.version;
+    const lockedDeclaration = lock?.packages?.['']?.[section]?.['@fastang/core'];
+    log(`@fastang/core: declared ${declared}; locked ${locked ?? 'unknown'}; installed ${current ?? 'missing'}; target ${metadata.version}`);
+    if (lock && ![2, 3].includes(lock.lockfileVersion))
+        problems.push('Unsupported lockfile format. Regenerate with a supported npm version.');
+    if (lock && lockedDeclaration !== declared)
+        problems.push('Manifest and lockfile declarations differ. Run npm install and review the diff first.');
+    if (lock && (!valid(locked) || locked !== current))
+        problems.push('Lockfile and installed core differ. Run npm ci first.');
+    if (current && validRange(declared) && !satisfies(current, declared))
+        problems.push('Installed core does not satisfy the manifest declaration. Reconcile the manifest and installation first.');
+    const downgrade = current && lt(metadata.version, current);
+    if (downgrade)
+        log('DOWNGRADE: target is older than the installed core.');
+    if (!current)
+        problems.push('Cannot determine installed core. Run npm install first.');
+    if (metadata.engines?.node) {
+        const ok = satisfies(process.versions.node, metadata.engines.node);
+        log(`Node ${process.versions.node}: ${ok ? 'OK' : 'INCOMPATIBLE'} (requires ${metadata.engines.node})`);
+        if (!ok)
+            problems.push('Node does not satisfy the target engine requirement.');
+    }
+    for (const [name, range] of Object.entries(metadata.peerDependencies ?? {})) {
+        const version = await installedVersion(name, directory);
+        const optional = metadata.peerDependenciesMeta?.[name]?.optional === true;
+        const ok = version ? satisfies(version, range) : optional;
+        log(`${name}: ${version ?? 'not installed'} — ${ok ? 'OK' : 'INCOMPATIBLE'} (requires ${range}${optional ? ', optional' : ''})`);
+        if (!ok)
+            problems.push(`${name} must satisfy ${range}.`);
+    }
+    log('Read the release migration notes and commit your app and lockfile first. App source files are not migrated.');
+    if (current === metadata.version && !problems.length) {
+        log('Already installed. No changes.');
+        return;
+    }
+    if (!apply) {
+        for (const problem of problems)
+            log(problem);
+        log(`Plan only. Apply with: fastang-cli update --to ${metadata.version} --yes${downgrade ? ' --allow-downgrade' : ''}`);
+        return;
+    }
+    if (downgrade && !allowDowngrade)
+        throw new Error('Downgrade blocked. Use --allow-downgrade explicitly.');
+    if (problems.length)
+        throw new Error(problems.join('\n'));
+    if (resolve(directory) !== resolve(process.cwd()))
+        throw new Error('Apply must run from the app directory.');
+    await npm(['install', section === 'devDependencies' ? '--save-dev' : '--save-prod', '--save-exact', '--engine-strict', '--strict-peer-deps', `@fastang/core@${metadata.version}`]);
+    log('Dependency updated. Review the diff, apply any documented migrations, then run your build and tests.');
+}

package/dist/process.d.ts

@@ -0,0 +1,8 @@
+export declare class ProcessError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+export declare function runProcess(command: string, args: string[], options?: {
+    capture?: boolean;
+    shell?: boolean;
+}): Promise<string>;

package/dist/process.js

@@ -0,0 +1,44 @@
+import { spawn } from 'node:child_process';
+export class ProcessError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+    }
+}
+export function runProcess(command, args, options = {}) {
+    return new Promise((resolveRun, reject) => {
+        const child = spawn(command, args, { stdio: options.capture ? ['ignore', 'pipe', 'inherit'] : 'inherit', shell: options.shell ?? false, detached: process.platform !== 'win32' });
+        let output = '';
+        const forward = (signal) => {
+            try {
+                if (process.platform !== 'win32' && child.pid)
+                    process.kill(-child.pid, signal);
+                else
+                    child.kill(signal);
+            }
+            catch (error) {
+                if (error.code !== 'ESRCH')
+                    throw error;
+            }
+        };
+        const interrupt = () => forward('SIGINT');
+        const terminate = () => forward('SIGTERM');
+        process.on('SIGINT', interrupt);
+        process.on('SIGTERM', terminate);
+        const cleanup = () => {
+            process.removeListener('SIGINT', interrupt);
+            process.removeListener('SIGTERM', terminate);
+        };
+        child.stdout?.on('data', chunk => { output += String(chunk); });
+        child.on('error', error => { cleanup(); reject(error); });
+        child.on('close', (code, signal) => {
+            cleanup();
+            const status = code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1);
+            if (status === 0)
+                resolveRun(output);
+            else
+                reject(new ProcessError(status, `${command} ${signal ? `terminated by ${signal}` : `exited with code ${status}`}`));
+        });
+    });
+}

package/package.json

@@ -1,6 +1,43 @@
 {
   "name": "@fastang/cli",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.3",
+  "type": "module",
+  "description": "Lightweight FastAng project CLI.",
+  "license": "MIT",
+  "author": "Dario Chiapperini",
+  "engines": {
+    "node": "^22.22.3 || ^24.15.0 || >=26.0.0"
+  },
+  "bin": {
+    "fastang": "./bin/fastang.mjs",
+    "fastang-cli": "./bin/fastang.mjs"
+  },
+  "files": [
+    "bin",
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "prepack": "npm run build"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/daclab-dev/fastang.git",
+    "directory": "packages/cli"
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "alpha",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "homepage": "https://fastang.dev",
+  "bugs": {
+    "url": "https://github.com/daclab-dev/fastang/issues"
+  },
+  "dependencies": {
+    "semver": "^7.7.2"
+  }
+}