@appinit/cli 1.1.0 → 1.3.0

package/LICENSE

@@ -0,0 +1,68 @@
+# AppInit CLI License (Proprietary – Compiled Distribution Only)
+
+Copyright © 2025 Pradeep, AppInit OS Authors
+All Rights Reserved.
+
+---
+
+## Grant of Permission
+
+Permission is hereby granted, free of charge, to any person who obtains an
+**official, unmodified, compiled distribution** of the AppInit CLI package
+(`appinit`, the “Software”) to install and use the Software solely for
+project initialization and related workflows on local or authorized environments,
+subject to the restrictions below.
+
+This license applies **only** to the compiled CLI distributable and does **not**
+grant access to source code, internal implementations, or architectural details.
+
+---
+
+## Permitted Uses
+
+You may:
+
+1. Install and execute the official AppInit CLI via approved distribution channels
+   (e.g. `npx appinit`, `npm install --global appinit`)
+2. Use the CLI to initialize projects and install owner-approved templates or addons
+3. Modify, extend, and distribute the **generated output** created by the CLI
+4. Develop addons, plugins, or templates using AppInit’s public APIs or SDKs
+   (when officially provided)
+
+---
+
+## Prohibited Uses
+
+You may **not**:
+
+1. Copy, extract, clone, or otherwise access the CLI’s internal implementation,
+   bundled engine, or private modules
+2. Reverse engineer, decompile, disassemble, or de-bundle the Software
+3. Republish or disclose internal architecture, resolution logic, or system behavior
+4. Create derivative tools, generators, runtimes, or competing systems based on
+   AppInit’s internal implementation
+5. Distribute modified versions of the AppInit CLI or its core components as
+   standalone or competing products
+
+---
+
+## Attribution
+
+This license notice must be included in all written references to the
+official AppInit CLI distributable.
+
+---
+
+## Disclaimer of Warranty
+
+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 NON-INFRINGEMENT.
+
+---
+
+## Limitation of Liability
+
+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 OF THE SOFTWARE.

package/README.md

@@ -1,111 +1,43 @@
-# **@appinit/cli**
+# AppInit CLI
 
-The official command-line interface for **AppInit OS**.
+The official AppInit command-line interface for creating projects from built-in templates.
 
-`@appinit/cli` provides all executable commands used to create, configure, and manage AppInit projects.
-It connects the user experience (prompts, commands, flags) with the internal systems (core engine, resolver, and template/module execution pipeline).
+## Requirements
 
-This is the primary entrypoint for developers using AppInit.
+- Node.js 20.11 or newer
+- npm, pnpm, yarn, or bun for installing generated project dependencies
 
----
+## Install
 
-## 📦 About
+Run without installing:
 
-`@appinit/cli` enables:
-
-- project creation
-
-  ```
-  appinit create <project-name>
-  ```
-
-- feature / module installation
-
-  ```
-  appinit add <feature>
-  ```
-
-- generating components, routes, API handlers
-
-  ```
-  appinit generate <component|page|api>
-  ```
-
-- doctor, sync, upgrade, debugging tools
-
-  ```
-  appinit doctor
-  appinit sync
-  appinit upgrade
-  ```
-
-- interactive prompts powered by **APS (AppInit Prompt Spec)**
-
-- smart suggestions & stack detection
-
-- safe, deterministic scaffolding
-
-The CLI orchestrates interactions between:
-
-- **resolver** (`@appinit/resolver`)
-- **engine** (`@appinit/engine`)
-- **core context** (`@appinit/core`)
-- **types & specs** (`@appinit/types`)
-
----
-
-## 📘 Usage
-
-Global usage:
-
-```sh
-npx appinit create my-app
-```
-
-Local workspace usage:
-
-```sh
-pnpm appinit create my-app
-```
-
-Internal usage:
-
-```ts
-import { runCLI } from "@appinit/cli";
-
-runCLI(process.argv.slice(2));
-```
-
----
-
-## 🛠 Development
-
-Build:
-
-```
-pnpm -F @appinit/cli build
+```bash
+npx @appinit/cli --help
+npx @appinit/cli create my-app
 ```
 
-Watch mode:
+Or install globally:
 
-```
-pnpm -F @appinit/cli dev
+```bash
+npm install --global @appinit/cli
+appinit create my-app
 ```
 
-Type-check:
+## Commands
 
-```
-pnpm -F @appinit/cli typecheck
-```
-
-Run locally (linked):
-
-```
-pnpm -F @appinit/cli appinit create test
+```bash
+appinit --help
+appinit create --help
+appinit template list
+appinit doctor
+appinit history
+appinit context
+appinit state inspect
+appinit validate
 ```
 
----
+AppInit includes the built-in Express, Fastify, Next.js, React, and Vue template families. You can also point the CLI at a custom template directory with `--template-dir` or `APPINIT_TEMPLATES_DIR`.
 
-## 📄 License
+## License
 
-Internal – © AppInit
+The compiled CLI is distributed under the proprietary license included in the `LICENSE` file. The private workspace implementation is not included as source code.

package/dist/index.d.ts

@@ -1,4 +1,373 @@
 #!/usr/bin/env node
-declare function start(argv: string[]): void;
+interface CreateCommandOptions {
+    readonly template?: string;
+    readonly target?: string;
+    readonly dryRun: boolean;
+    readonly yes: boolean;
+    readonly templateDirectory?: string;
+    readonly variables: Readonly<Record<string, unknown>>;
+    readonly install: boolean;
+    readonly git: boolean;
+    readonly packageManager?: "pnpm" | "npm" | "yarn" | "bun";
+}
+declare function parseCreateArguments(args: readonly string[]): CreateCommandOptions;
 
-export { start };
+/**
+ * TemplateKind
+ * ──────────────────────────────────────────────────────────────
+ *
+ * Declares **what a template represents architecturally**.
+ *
+ * A TemplateKind describes the **role of the template itself**,
+ * not the artifact it produces.
+ *
+ * Templates are NOT artifacts.
+ * They are **blueprints** that can generate artifacts.
+ *
+ * This distinction is critical for:
+ * - ATS 2.0 composition
+ * - capability reuse
+ * - future marketplace semantics
+ *
+ * ATS 1.0 implicitly assumed all templates were "project".
+ * ATS 2.0 makes this explicit and extensible.
+ *
+ * ──────────────────────────────────────────────────────────────
+ * Design invariants (LOCKED)
+ * ──────────────────────────────────────────────────────────────
+ *
+ * 1. TemplateKind MUST NOT:
+ *    ❌ imply filesystem layout
+ *    ❌ imply execution behavior
+ *    ❌ imply ArtifactKind
+ *
+ * 2. TemplateKind MAY:
+ *    - influence validation rules
+ *    - influence resolver behavior
+ *    - enable composition semantics (ATS 2.0)
+ *
+ * 3. TemplateKind is REQUIRED metadata
+ *    in TemplateConfig.
+ *
+ * ──────────────────────────────────────────────────────────────
+ * Used by
+ * ──────────────────────────────────────────────────────────────
+ *
+ * - TemplateConfig
+ * - Resolver
+ * - Validator
+ * - Doctor
+ * - Marketplace / registry
+ */
+type TemplateKind = 
+/**
+ * Project template
+ *
+ * Represents a full, standalone project.
+ */
+"project"
+/**
+ * Module template
+ *
+ * Represents a reusable module intended
+ * to be integrated into a project.
+ */
+ | "module"
+/**
+ * Capability template
+ *
+ * Represents a composable feature or concern
+ * (e.g. auth, linting, CI).
+ *
+ * Not standalone.
+ */
+ | "capability"
+/**
+ * Preset template
+ *
+ * Represents a predefined combination
+ * of templates or capabilities.
+ */
+ | "preset"
+/**
+ * Composition template
+ *
+ * Represents a higher-order template that
+ * composes other templates.
+ *
+ * ATS 2.0 only.
+ */
+ | "composition";
+
+type TemplateRendererEngine = "liquid" | "none";
+interface TemplateManifest {
+    readonly schemaVersion: 1;
+    readonly id: string;
+    readonly version: string;
+    readonly kind: TemplateKind;
+    readonly atsVersion: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: string;
+    readonly language: string;
+    readonly packageName: string;
+    readonly renderer: {
+        readonly engine: TemplateRendererEngine;
+    };
+    readonly paths: {
+        readonly template: string;
+        readonly variables?: string;
+        readonly hooks?: string;
+    };
+    readonly tags: readonly string[];
+    /** Capability identifiers this template requires from other selected templates. */
+    readonly requires?: readonly string[];
+    /** Capability identifiers this template provides to other selected templates. */
+    readonly provides?: readonly string[];
+    /** Template IDs or capability identifiers incompatible with this template. */
+    readonly conflicts?: readonly string[];
+}
+
+interface VirtualFile {
+    /** Normalized POSIX path relative to the generated project root. */
+    dest: string;
+    content: string | Buffer;
+    /** Whether the content should pass through a template renderer. */
+    render: boolean;
+    /** Whether content is binary and must not be decoded as UTF-8. */
+    binary: boolean;
+}
+
+declare class VirtualFileSystem {
+    private readonly files;
+    add(file: VirtualFile): void;
+    get(destination: string): VirtualFile | undefined;
+    list(): Iterable<VirtualFile>;
+    remove(destination: string): boolean;
+    updateContent(destination: string, content: string | Buffer): void;
+    get size(): number;
+}
+
+interface AppInitProjectHistoryEntry {
+    readonly path: string;
+    readonly templateId: string;
+    readonly createdAt: string;
+}
+interface AppInitState {
+    readonly schemaVersion: 1;
+    readonly projects: readonly AppInitProjectHistoryEntry[];
+    /** Fields retained for compatibility with the existing update-check state. */
+    readonly lastUpdateCheck?: unknown;
+    readonly latestVersion?: unknown;
+}
+
+interface ResolvedTemplate {
+    readonly root: string;
+    readonly manifest: TemplateManifest;
+    readonly vfs: VirtualFileSystem;
+}
+
+interface LocalTemplate {
+    readonly id: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: string;
+    readonly root: string;
+    readonly template: ResolvedTemplate;
+}
+interface ResolvedCreateOptions extends CreateCommandOptions {
+    readonly template: string;
+    readonly target: string;
+}
+declare function runCreateCommand(options: ResolvedCreateOptions): Promise<void>;
+
+interface ContextCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+interface ContextCommandIO {
+    readonly write: (message: string) => void;
+}
+type JsonRecord = Record<string, unknown>;
+interface ProjectContextReport {
+    readonly rootDir: string;
+    readonly package?: {
+        readonly name?: string;
+        readonly version?: string;
+    };
+    readonly appinit?: {
+        readonly project?: JsonRecord;
+        readonly template?: JsonRecord;
+        readonly context?: JsonRecord;
+    };
+    readonly history?: AppInitProjectHistoryEntry;
+    readonly diagnostics: readonly string[];
+}
+/** Collect the current project's existing metadata and matching global history. */
+declare function readProjectContext(cwd?: string): Promise<ProjectContextReport>;
+/** Display the current project's AppInit metadata and related global history. */
+declare function runContextCommand(options?: ContextCommandOptions, io?: ContextCommandIO): Promise<void>;
+
+type PackageManager = "pnpm" | "npm" | "yarn" | "bun";
+
+interface FinalizeOptions {
+    readonly install: boolean;
+    readonly git: boolean;
+    readonly packageManager?: PackageManager;
+}
+interface FinalizeIO {
+    readonly interactive: boolean;
+    ask(message: string, fallback?: string): Promise<string>;
+    confirm(message: string): Promise<boolean>;
+    write(message: string): void;
+}
+declare function finalizeProject(directory: string, options: FinalizeOptions, io: FinalizeIO): Promise<void>;
+
+interface DoctorCommandIO {
+    write(message: string): void;
+}
+interface DoctorCommandOptions {
+    readonly cwd?: string;
+    readonly json?: boolean;
+}
+declare function runDoctorCommand(options?: DoctorCommandOptions, io?: DoctorCommandIO): Promise<void>;
+
+interface HistoryCommandOptions {
+    readonly json?: boolean;
+}
+interface HistoryCommandIO {
+    readonly write: (message: string) => void;
+}
+/** Read and validate the user's global project history. */
+declare function readProjectHistory(): Promise<AppInitState>;
+/** Render previously generated projects from the global AppInit state file. */
+declare function runHistoryCommand(options?: HistoryCommandOptions, io?: HistoryCommandIO): Promise<void>;
+
+interface StatePathCommandOptions {
+    /** Environment source is injectable for deterministic tests. */
+    readonly env?: NodeJS.ProcessEnv;
+    /** Home directory source is injectable for deterministic tests. */
+    readonly homeDirectory?: string;
+}
+interface StatePathCommandIO {
+    readonly write: (message: string) => void;
+}
+interface AppInitStatePathInfo {
+    readonly path: string;
+    readonly source: "APPINIT_HOME" | "default";
+    readonly exists: boolean;
+    readonly isDirectory: boolean;
+}
+/** Inspect the configured global state path without creating or modifying it. */
+declare function inspectAppInitStatePath(options?: StatePathCommandOptions): Promise<AppInitStatePathInfo>;
+/** Print the resolved global state location and whether it is initialized. */
+declare function runStatePathCommand(options?: StatePathCommandOptions, io?: StatePathCommandIO): Promise<void>;
+
+interface StateInspectCommandOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDirectory?: string;
+    readonly json?: boolean;
+}
+interface StateInspectCommandIO {
+    readonly write: (message: string) => void;
+}
+interface AppInitStateInspection {
+    readonly path: string;
+    readonly source: "APPINIT_HOME" | "default";
+    readonly stateFile: "missing" | "valid" | "invalid";
+    readonly schemaVersion?: number;
+    readonly projectCount?: number;
+    readonly diagnostics: readonly string[];
+}
+/** Inspect global state without creating, repairing, or modifying persisted data. */
+declare function inspectAppInitState(options?: StateInspectCommandOptions): Promise<AppInitStateInspection>;
+/** Display a safe summary of global state; project paths and stored values are not exposed. */
+declare function runStateInspectCommand(options?: StateInspectCommandOptions, io?: StateInspectCommandIO): Promise<void>;
+
+interface StateDoctorOptions {
+    readonly env?: NodeJS.ProcessEnv;
+    readonly homeDirectory?: string;
+    readonly json?: boolean;
+}
+interface StateDoctorIO {
+    readonly write: (message: string) => void;
+}
+interface StateDoctorDiagnostic {
+    readonly code: string;
+    readonly level: "info" | "warn" | "error";
+    readonly message: string;
+    readonly hint?: string;
+}
+interface StateDoctorReport {
+    readonly path: string;
+    readonly source: "APPINIT_HOME" | "default";
+    readonly stateFile: "missing" | "valid" | "invalid";
+    readonly ok: boolean;
+    readonly diagnostics: readonly StateDoctorDiagnostic[];
+    readonly summary: Readonly<{
+        info: number;
+        warn: number;
+        error: number;
+    }>;
+}
+/** Diagnose global state health without creating, repairing, or modifying files. */
+declare function diagnoseAppInitState(options?: StateDoctorOptions): Promise<StateDoctorReport>;
+/** Print a human-readable or machine-readable global state health report. */
+declare function runStateDoctorCommand(options?: StateDoctorOptions, io?: StateDoctorIO): Promise<void>;
+
+interface ValidateCommandIO {
+    write(message: string): void;
+}
+interface ValidateCommandOptions {
+    readonly cwd?: string;
+    readonly templateDir?: string;
+    readonly json?: boolean;
+}
+declare function runValidateCommand(options?: ValidateCommandOptions, io?: ValidateCommandIO): Promise<void>;
+
+interface RemoteTemplateOptions {
+    readonly registryUrl: string;
+    readonly templateId?: string;
+    readonly version?: string;
+    readonly cacheDirectory?: string;
+    readonly templatesDirectory?: string;
+    readonly fetch?: typeof fetch;
+}
+interface RemoteTemplateListing {
+    readonly id: string;
+    readonly version: string;
+    readonly name: string;
+    readonly description: string;
+    readonly category: string;
+    readonly language: string;
+    readonly tags: readonly string[];
+}
+declare function listRemoteTemplates(options: RemoteTemplateOptions): Promise<readonly RemoteTemplateListing[]>;
+/**
+ * Download, verify, safely extract, and validate one exact registry version.
+ * Registry archives must contain appinit.template.json at their archive root.
+ */
+declare function installRemoteTemplate(options: RemoteTemplateOptions & {
+    readonly templateId: string;
+    readonly version?: string;
+}): Promise<{
+    readonly id: string;
+    readonly version: string;
+    readonly directory: string;
+    readonly cached: boolean;
+}>;
+
+declare function searchLocalTemplates(templates: readonly LocalTemplate[], query: string): readonly LocalTemplate[];
+declare function findLocalTemplate(templates: readonly LocalTemplate[], reference: string): LocalTemplate | undefined;
+declare function formatTemplateList(templates: readonly LocalTemplate[], heading?: string): string;
+declare function formatTemplateInfo(template: LocalTemplate): string;
+
+interface CreateWizardIO {
+    readonly interactive: boolean;
+    ask(message: string, fallback?: string): Promise<string>;
+    confirm(message: string): Promise<boolean>;
+    write(message: string): void;
+}
+declare function resolveGuidedCreate(options: CreateCommandOptions, io: CreateWizardIO): Promise<ResolvedCreateOptions | null>;
+
+export { diagnoseAppInitState, finalizeProject, findLocalTemplate, formatTemplateInfo, formatTemplateList, inspectAppInitState, inspectAppInitStatePath, installRemoteTemplate, listRemoteTemplates, parseCreateArguments, readProjectContext, readProjectHistory, resolveGuidedCreate, runContextCommand, runCreateCommand, runDoctorCommand, runHistoryCommand, runStateDoctorCommand, runStateInspectCommand, runStatePathCommand, runValidateCommand, searchLocalTemplates };