@chidchanun/bcp 0.1.28 → 0.1.29

package/docs/project-metadata.md

@@ -0,0 +1,112 @@
+# Project Metadata
+
+BCP Framework `0.1.29` makes generated project presets explicit through `bcp.project.json`.
+
+`create-bcp-app` writes this file after applying the selected project options.
+
+Example:
+
+```json
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "projectName": "my-app",
+  "frameworkPackage": "npm:@chidchanun/bcp@0.1.29",
+  "createdWith": {
+    "package": "create-bcp-app",
+    "version": "0.1.29"
+  },
+  "packageManager": "npm",
+  "presets": {
+    "tailwind": true,
+    "database": "mysql",
+    "auth": "jwt-cookie",
+    "storage": "cloudflare-r2"
+  }
+}
+```
+
+## Purpose
+
+The metadata file records scaffold choices without requiring later tools to infer them from source code.
+
+It is intended for:
+
+- `bcp doctor`,
+- `bcp inspect`,
+- project migration/update tooling,
+- documentation tooling,
+- `bcp-docs-web` examples and project-aware guidance,
+- future framework upgrade diagnostics.
+
+## Security boundary
+
+`bcp.project.json` must not contain credentials or runtime secrets.
+
+It records only non-secret configuration identities such as:
+
+```text
+Tailwind enabled/disabled
+Database preset name
+Auth preset name
+Storage provider name
+Package manager
+Framework package specifier
+create-bcp-app version
+```
+
+Do not add values such as:
+
+```text
+AWS_ACCESS_KEY_ID
+AWS_SECRET_ACCESS_KEY
+R2_ACCESS_KEY_ID
+R2_SECRET_ACCESS_KEY
+DATABASE_URL
+passwords
+JWT secrets
+session tokens
+```
+
+Runtime configuration stays in environment variables and server-only configuration.
+
+## Schema version
+
+The initial format uses:
+
+```json
+{
+  "schemaVersion": 1
+}
+```
+
+Consumers should check `schemaVersion` before relying on optional metadata fields.
+
+Unknown future fields should normally be ignored so newer `create-bcp-app` versions remain compatible with older tooling where practical.
+
+## Storage provider metadata
+
+Storage choices currently include:
+
+```text
+none
+local
+amazon-s3
+cloudflare-r2
+```
+
+`bcp inspect` can use the metadata first and fall back to inspecting `lib/storage.ts` for older projects without `bcp.project.json`.
+
+## Existing projects
+
+Projects created before `0.1.29` do not need this file to keep running.
+
+The metadata file is additive. Doctor/inspect can still infer core project information from `package.json`, lockfiles, routes and generated source where possible.
+
+If an older project wants to adopt the file manually, keep the schema minimal and do not invent preset values that are not actually in use.
+
+## Source control
+
+`bcp.project.json` should normally be committed to source control because it contains project structure metadata, not secrets.
+
+This allows CI and documentation tooling to read the same preset identity as local developer tooling.

package/docs/releases/0.1.29.md

@@ -0,0 +1,170 @@
+# BCP Framework 0.1.29
+
+> **Milestone:** Developer Experience
+>
+> **Release state:** unreleased development target. Do not mark this version as published until local validation, RC checks, tagging and npm publication complete.
+
+BCP Framework `0.1.29` focuses on reducing repetitive project setup and making project diagnostics easier to consume locally, in CI and in `bcp-docs-web`.
+
+## Highlights
+
+### Project generators
+
+New CLI command:
+
+```bash
+bcp generate <kind>
+```
+
+Supported generators:
+
+```bash
+bcp generate page dashboard/users
+bcp generate api users
+bcp generate middleware
+bcp generate migration create_users
+```
+
+Page, API and middleware generators refuse to replace existing files unless `--force` is explicitly supplied.
+
+Migration generation reuses the existing database migration implementation so timestamp/file naming has a single source of truth.
+
+### Doctor / Inspect v2
+
+`bcp doctor` now adds project/runtime checks for:
+
+- supported dependency lockfiles,
+- duplicate `bcp` / `@chidchanun/bcp` dependency declarations,
+- production hardening environment validity,
+- standalone production build presence,
+- Docker + lockfile reproducibility guidance,
+- configured storage provider detection.
+
+`bcp inspect` keeps its previous report fields and adds a `project` section with:
+
+```text
+package manager
+lockfile
+bcp.project.json metadata
+selected create-bcp-app presets
+production build presence
+Dockerfile presence
+framework dependency declarations
+storage provider
+production hardening state
+```
+
+The new fields are additive so existing consumers of the previous JSON fields can continue reading them.
+
+### `bcp.project.json`
+
+New projects created by `create-bcp-app` receive a non-secret metadata manifest:
+
+```json
+{
+  "schemaVersion": 1,
+  "framework": "bcp",
+  "projectName": "my-app",
+  "createdWith": {
+    "package": "create-bcp-app",
+    "version": "0.1.29"
+  },
+  "packageManager": "npm",
+  "presets": {
+    "tailwind": true,
+    "database": "mysql",
+    "auth": "jwt-cookie",
+    "storage": "local"
+  }
+}
+```
+
+The manifest records scaffold identity only. Credentials, passwords, access keys, session secrets and tokens must remain outside this file.
+
+Older projects without `bcp.project.json` continue to work. Doctor/inspect fall back to project files where practical.
+
+### Docs-web manifest
+
+`docs/docs-web-manifest.json` is now the explicit navigation contract for `bcp-docs-web`.
+
+It maps:
+
+```text
+section
+website route
+Markdown source
+title
+release routes
+version target
+release state
+```
+
+The Markdown files under `docs/` remain the authored documentation source of truth. The JSON manifest is navigation/routing metadata, not a competing content source.
+
+New authored guides include:
+
+- `docs/generators.md`
+- `docs/project-metadata.md`
+
+## Compatibility
+
+`0.1.29` is intended to be additive.
+
+- Existing page/API routing remains unchanged.
+- Existing database migration commands remain supported.
+- `bcp doctor` retains its existing report structure and adds checks.
+- `bcp inspect` retains its existing fields and adds `project`.
+- Existing projects do not require `bcp.project.json`.
+- `--force` is opt-in and never silently overwrites existing generated files.
+
+## Out of scope
+
+The following are not guarantees of `0.1.29`:
+
+- generated symbol/API reference documentation,
+- interactive documentation playgrounds,
+- source-code merge behavior for generators,
+- automatic conversion of old projects into `bcp.project.json`,
+- the `0.2.0` API/platform stability baseline.
+
+## Documentation sources
+
+Primary documentation for this milestone:
+
+```text
+docs/generators.md
+docs/developer-tools.md
+docs/project-metadata.md
+docs/docs-web-manifest.json
+docs/README.md
+```
+
+## Validation
+
+Before tagging or publishing `0.1.29`, run:
+
+```powershell
+npm run typecheck
+npm run test:unit
+npm run test:integration
+npm run test:package
+npm run test:e2e
+npm run rc:check
+```
+
+The release lockfile must also be synchronized to `0.1.29` before the final tag.
+
+Recommended generator smoke checks:
+
+```powershell
+npm exec -- bcp-framework generate page dx-test --root examples/basic-app
+npm exec -- bcp-framework routes --root examples/basic-app
+```
+
+Use a disposable project for destructive `--force` testing.
+
+## Next direction
+
+After `0.1.29`, the planned major milestone is **`0.2.0 — Framework Platform`**.
+
+The `0.2.0` work should focus on consolidating the existing `0.1.x` surface into a documented platform baseline: API consistency, production stabilization, documentation completeness, migration guidance and compatibility expectations rather than adding unrelated large feature areas.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chidchanun/bcp",
-  "version": "0.1.28",
+  "version": "0.1.29",
   "description": "BCP Framework - a React full-stack framework with file-based routing, SSR, APIs, middleware, islands, caching and standalone production builds.",
   "type": "module",
   "license": "MIT",

package/packages/cli/src/args.ts

@@ -8,6 +8,7 @@ export type CliCommand =
   | "routes"
   | "update"
   | "db"
+  | "generate"
   | "doctor"
   | "inspect"
   | "help"
@@ -20,6 +21,13 @@ export type DatabaseCliAction =
   | "create"
   | "help";
 
+export type GenerateCliKind =
+  | "page"
+  | "api"
+  | "middleware"
+  | "migration"
+  | "help";
+
 export interface CliOptions {
   command: CliCommand;
 
@@ -37,9 +45,15 @@ export interface CliOptions {
 
   json?: boolean;
 
+  force?: boolean;
+
   dbAction?: DatabaseCliAction;
 
   dbMigrationName?: string;
+
+  generateKind?: GenerateCliKind;
+
+  generateName?: string;
 }
 
 export function parseCliArgs(
@@ -68,12 +82,21 @@ export function parseCliArgs(
   let json =
     false;
 
+  let force =
+    false;
+
   let dbAction:
     DatabaseCliAction | undefined;
 
   let dbMigrationName:
     string | undefined;
 
+  let generateKind:
+    GenerateCliKind | undefined;
+
+  let generateName:
+    string | undefined;
+
   let commandSet = false;
 
   for (
@@ -92,6 +115,11 @@ export function parseCliArgs(
         command === "db"
       ) {
         dbAction = "help";
+      } else if (
+        commandSet &&
+        command === "generate"
+      ) {
+        generateKind = "help";
       } else {
         command = "help";
       }
@@ -224,6 +252,14 @@ export function parseCliArgs(
       continue;
     }
 
+    if (
+      argument === "--force"
+    ) {
+      force =
+        true;
+      continue;
+    }
+
     if (
       argument.startsWith("-")
     ) {
@@ -299,6 +335,45 @@ export function parseCliArgs(
       );
     }
 
+    if (
+      commandSet &&
+      command === "generate"
+    ) {
+      if (
+        generateKind === undefined
+      ) {
+        if (
+          argument === "page" ||
+          argument === "api" ||
+          argument === "middleware" ||
+          argument === "migration" ||
+          argument === "help"
+        ) {
+          generateKind =
+            argument;
+          continue;
+        }
+
+        throw new Error(
+          `Unknown generator: ${argument}`
+        );
+      }
+
+      if (
+        generateKind !== "middleware" &&
+        generateKind !== "help" &&
+        generateName === undefined
+      ) {
+        generateName =
+          argument;
+        continue;
+      }
+
+      throw new Error(
+        `Unexpected argument: ${argument}`
+      );
+    }
+
     if (commandSet) {
       throw new Error(
         `Unexpected argument: ${argument}`
@@ -312,6 +387,7 @@ export function parseCliArgs(
       argument === "routes" ||
       argument === "update" ||
       argument === "db" ||
+      argument === "generate" ||
       argument === "doctor" ||
       argument === "inspect" ||
       argument === "help" ||
@@ -349,6 +425,15 @@ export function parseCliArgs(
     );
   }
 
+  if (
+    force &&
+    command !== "generate"
+  ) {
+    throw new Error(
+      "Option --force is only valid with `bcp generate`."
+    );
+  }
+
   return {
     command,
     rootDirectory,
@@ -362,12 +447,23 @@ export function parseCliArgs(
           json: true,
         }
       : {}),
+    ...(force
+      ? {
+          force: true,
+        }
+      : {}),
     ...(command === "db"
       ? {
           dbAction,
           dbMigrationName,
         }
       : {}),
+    ...(command === "generate"
+      ? {
+          generateKind,
+          generateName,
+        }
+      : {}),
   };
 }