create-zass-project 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dzuddiyn
+
+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,87 @@
-# Temporary Holding Version
+# create-zass-project
 
-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.
+Bootstrap a new local ZASS project from one explicitly selected official method and language.
+
+## Requirements
+
+- Node.js 20 or newer
+- npm
+
+## Quick start
+
+Interactive:
+
+```bash
+npm create zass-project@latest my-project
+```
+
+Non-interactive:
+
+```bash
+npm create zass-project@latest my-project -- --method zassimple --lang en
+```
+
+Supported methods:
+
+- `zasspill`
+- `zasselection`
+- `zassimple`
+- `zass` — Full ZASS
+
+Supported languages:
+
+- `en` — English
+- `my` — Bahasa Melayu
+
+No method or language is silently selected. In a non-interactive environment, both `--method` and `--lang` are required.
+
+## What it creates
+
+A successful bootstrap creates exactly:
+
+- one selected ZASS method file;
+- `README.md`;
+- `.gitignore`.
+
+For Full ZASS, the project authority file is always `ZASS.md`, including when Bahasa Melayu is selected.
+
+## Safety and side effects
+
+v0.1 is create-new-only. If the target already exists, `create-zass-project` refuses to overwrite or merge it.
+
+It does **not**:
+
+- initialize Git;
+- create or connect a GitHub repository;
+- register CrossAI;
+- call Google Drive or an AI API;
+- send telemetry;
+- install dependencies inside the generated project;
+- download ZASS method templates at runtime.
+
+Generated `.gitignore` includes a baseline for common secret files. Do not put passwords, API keys, tokens, or sensitive personal data into tracked ZASS Markdown files.
+
+## Package architecture
+
+Project semantics come from the repository's frozen private Bootstrap Core. The npm package carries a byte-for-byte vendored runtime snapshot under `vendor/bootstrap-core/`, and repository tests enforce synchronization with canonical Core `src/` and `templates/`.
+
+## Development
+
+Public npm package candidate: `create-zass-project@0.1.0`.
+
+The repository implementation directory remains `create-zass/`.
+
+From this repository:
+
+```bash
+node create-zass/bin/create-zass.js my-project --method zassimple --lang en
+npm --prefix create-zass test
+```
+
+## Issues
+
+Report issues in the ZASS repository issue tracker.
+
+## License
+
+MIT

package/bin/create-zass.js

@@ -0,0 +1,38 @@
+#!/usr/bin/env node
+
+import { bootstrapProject, formatSuccess } from '../src/bootstrap.js';
+import { UsageError } from '../src/errors.js';
+import { parseArgs, resolveSelections } from '../src/options.js';
+import { defaultPrompt } from '../src/prompts.js';
+
+const USAGE = [
+  'Usage:',
+  '  create-zass-project <project> [--method <zasspill|zasselection|zassimple|zass>] [--lang <en|my>]'
+].join('\n');
+
+async function main() {
+  try {
+    const parsed = parseArgs(process.argv.slice(2));
+    const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+    const resolved = await resolveSelections(parsed, {
+      interactive,
+      prompt: (kind, choices) => defaultPrompt(kind, choices)
+    });
+
+    const report = await bootstrapProject(resolved);
+    console.log(formatSuccess(report));
+    process.exitCode = 0;
+  } catch (error) {
+    const refusal = error.exitCode === 1;
+    console.error('CREATE ZASS');
+    console.error('');
+    console.error(`${refusal ? 'REFUSED' : 'ERROR'} — ${error.message}`);
+    if (error instanceof UsageError) {
+      console.error('');
+      console.error(USAGE);
+    }
+    process.exitCode = error.exitCode ?? 2;
+  }
+}
+
+await main();

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "create-zass-project",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Bootstrap a local ZASS project with an explicitly selected official method and language",
+  "type": "module",
+  "bin": {
+    "create-zass-project": "bin/create-zass.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "vendor",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "node --test test/*.test.js",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "zass",
+    "cli",
+    "project-bootstrap",
+    "architecture",
+    "decision-making",
+    "ai"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dzuddiyn/ZASS-Zero-to-Architecture-Structured-Sprint.git",
+    "directory": "create-zass"
+  },
+  "homepage": "https://github.com/dzuddiyn/ZASS-Zero-to-Architecture-Structured-Sprint/tree/main/create-zass#readme",
+  "bugs": {
+    "url": "https://github.com/dzuddiyn/ZASS-Zero-to-Architecture-Structured-Sprint/issues"
+  },
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
+  "license": "MIT"
+}

package/src/bootstrap.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { constants } from 'node:fs';
+import {
+  buildBootstrapPlan,
+  getBootstrapDescriptor,
+  verifyBootstrapSnapshot
+} from '../vendor/bootstrap-core/src/index.js';
+import { BootstrapRefusalError } from './errors.js';
+
+async function pathExists(target) {
+  try {
+    await fs.lstat(target);
+    return true;
+  } catch (error) {
+    if (error.code === 'ENOENT') return false;
+    throw error;
+  }
+}
+
+async function readBootstrapSnapshot(projectDir) {
+  const entries = await fs.readdir(projectDir);
+  const files = [];
+
+  for (const name of entries) {
+    const fullPath = path.join(projectDir, name);
+    const stat = await fs.stat(fullPath);
+    if (!stat.isFile()) {
+      files.push({ path: name, content: null });
+      continue;
+    }
+
+    files.push({
+      path: name,
+      content: await fs.readFile(fullPath, 'utf8')
+    });
+  }
+
+  return { files };
+}
+
+export async function bootstrapProject(
+  { target, method, language },
+  dependencies = {}
+) {
+  const projectDir = path.resolve(target);
+  const parentDir = path.dirname(projectDir);
+  const projectName = path.basename(projectDir);
+  const writeFile = dependencies.writeFile ?? fs.writeFile;
+  const planBuilder = dependencies.buildPlan ?? buildBootstrapPlan;
+
+  if (await pathExists(projectDir)) {
+    throw new BootstrapRefusalError(`Target already exists: ${projectDir}`);
+  }
+
+  let parentStat;
+  try {
+    parentStat = await fs.stat(parentDir);
+  } catch (error) {
+    if (error.code === 'ENOENT') {
+      throw new BootstrapRefusalError(`Parent directory does not exist: ${parentDir}`);
+    }
+    throw error;
+  }
+
+  if (!parentStat.isDirectory()) {
+    throw new BootstrapRefusalError(`Parent path is not a directory: ${parentDir}`);
+  }
+
+  try {
+    await fs.access(parentDir, constants.W_OK);
+  } catch {
+    throw new BootstrapRefusalError(`Parent directory is not writable: ${parentDir}`);
+  }
+
+  const plan = await planBuilder({ projectName, method, language });
+  const descriptor = getBootstrapDescriptor(method, language);
+  let created = false;
+
+  try {
+    try {
+      await fs.mkdir(projectDir);
+      created = true;
+    } catch (error) {
+      if (error.code === 'EEXIST') {
+        throw new BootstrapRefusalError(`Target already exists: ${projectDir}`);
+      }
+      throw error;
+    }
+
+    for (const file of plan.files) {
+      await writeFile(path.join(projectDir, file.path), file.content, 'utf8');
+    }
+
+    const snapshot = await readBootstrapSnapshot(projectDir);
+    const verification = verifyBootstrapSnapshot(plan, snapshot);
+
+    if (!verification.ok) {
+      throw new Error(
+        `Materialized bootstrap verification failed: ${verification.errors
+          .map((entry) => entry.message)
+          .join('; ')}`
+      );
+    }
+
+    return {
+      ok: true,
+      projectName,
+      projectDir,
+      target,
+      method,
+      language,
+      methodFile: plan.project.methodFile,
+      methodLabel: descriptor.methodLabel,
+      languageLabel: descriptor.languageLabel,
+      createdFiles: plan.files.map((file) => file.path)
+    };
+  } catch (error) {
+    if (created) {
+      await fs.rm(projectDir, { recursive: true, force: true });
+    }
+    throw error;
+  }
+}
+
+export function formatSuccess(report) {
+  return [
+    'ZASS project created.',
+    '',
+    `Project:  ${report.projectName}`,
+    `Method:   ${report.methodLabel}`,
+    `Language: ${report.languageLabel}`,
+    '',
+    'Created:',
+    ...report.createdFiles.map((name) => `  ${name}`),
+    '',
+    'Git:      not initialized',
+    'GitHub:   not connected',
+    'CrossAI:  not registered',
+    '',
+    'Next:',
+    `  cd "${report.target}"`,
+    `  open ${report.methodFile} with your AI`
+  ].join('\n');
+}

package/src/errors.js

@@ -0,0 +1,15 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'UsageError';
+    this.exitCode = 2;
+  }
+}
+
+export class BootstrapRefusalError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = 'BootstrapRefusalError';
+    this.exitCode = 1;
+  }
+}

package/src/options.js

@@ -0,0 +1,105 @@
+import { UsageError } from './errors.js';
+import {
+  LANGUAGE_CHOICES,
+  METHOD_CHOICES
+} from '../vendor/bootstrap-core/src/index.js';
+import {
+  isSupportedLanguage,
+  isSupportedMethod
+} from '../vendor/bootstrap-core/src/catalog.js';
+
+export { LANGUAGE_CHOICES, METHOD_CHOICES };
+
+export function parseArgs(argv) {
+  let target;
+  let method;
+  let language;
+
+  for (let index = 0; index < argv.length; index += 1) {
+    const value = argv[index];
+
+    if (value === '--method' || value === '--lang') {
+      const next = argv[index + 1];
+      if (!next || next.startsWith('-')) {
+        throw new UsageError(`Missing value for ${value}`);
+      }
+
+      if (value === '--method') {
+        if (method !== undefined) throw new UsageError('Duplicate --method');
+        method = next;
+      } else {
+        if (language !== undefined) throw new UsageError('Duplicate --lang');
+        language = next;
+      }
+
+      index += 1;
+      continue;
+    }
+
+    if (value.startsWith('-')) {
+      throw new UsageError(`Unsupported option: ${value}`);
+    }
+
+    if (target !== undefined) {
+      throw new UsageError('Exactly one project target is required');
+    }
+
+    target = value;
+  }
+
+  if (!target) {
+    throw new UsageError('Project target is required');
+  }
+
+  return { target, method, language };
+}
+
+function validateMethod(method) {
+  if (!isSupportedMethod(method)) {
+    throw new UsageError(
+      `Invalid method: ${method}. Expected one of: ${METHOD_CHOICES.map((choice) => choice.value).join(', ')}`
+    );
+  }
+}
+
+function validateLanguage(language) {
+  if (!isSupportedLanguage(language)) {
+    throw new UsageError(
+      `Invalid language: ${language}. Expected one of: ${LANGUAGE_CHOICES.map((choice) => choice.value).join(', ')}`
+    );
+  }
+}
+
+export async function resolveSelections(
+  parsed,
+  { interactive = false, prompt } = {}
+) {
+  let { method, language } = parsed;
+
+  if (method !== undefined) validateMethod(method);
+  if (language !== undefined) validateLanguage(language);
+
+  if (method === undefined) {
+    if (!interactive) {
+      throw new UsageError('Method required in non-interactive mode; use --method');
+    }
+    if (typeof prompt !== 'function') {
+      throw new UsageError('Interactive method prompt is unavailable');
+    }
+    method = await prompt('method', METHOD_CHOICES);
+    validateMethod(method);
+  }
+
+  if (language === undefined) {
+    if (!interactive) {
+      throw new UsageError('Language required in non-interactive mode; use --lang');
+    }
+    if (typeof prompt !== 'function') {
+      throw new UsageError('Interactive language prompt is unavailable');
+    }
+    language = await prompt('language', LANGUAGE_CHOICES);
+    validateLanguage(language);
+  }
+
+  return { ...parsed, method, language };
+}

package/src/prompts.js

@@ -0,0 +1,42 @@
+import { createInterface } from 'node:readline/promises';
+
+export async function promptChoice(question, choices, io = {}) {
+  const input = io.input ?? process.stdin;
+  const output = io.output ?? process.stdout;
+  const rl = createInterface({ input, output });
+
+  try {
+    while (true) {
+      output.write(`${question}\n\n`);
+      for (let index = 0; index < choices.length; index += 1) {
+        const choice = choices[index];
+        const description = choice.description ? ` — ${choice.description}` : '';
+        output.write(`  ${index + 1}. ${choice.label}${description}\n`);
+      }
+      output.write('\n');
+
+      const answer = (await rl.question(`Select [1-${choices.length}]: `)).trim();
+      const selected = Number(answer);
+
+      if (
+        Number.isInteger(selected) &&
+        selected >= 1 &&
+        selected <= choices.length
+      ) {
+        return choices[selected - 1].value;
+      }
+
+      output.write(`Please choose a number from 1 to ${choices.length}.\n\n`);
+    }
+  } finally {
+    rl.close();
+  }
+}
+
+export async function defaultPrompt(kind, choices, io) {
+  const question =
+    kind === 'method'
+      ? 'Which ZASS method do you want to start with?'
+      : 'Choose language:';
+  return promptChoice(question, choices, io);
+}

package/vendor/bootstrap-core/src/catalog.js

@@ -0,0 +1,81 @@
+export const CORE_CONTRACT_VERSION = '0.1';
+
+export const METHOD_CHOICES = Object.freeze([
+  Object.freeze({ value: 'zasspill', label: 'ZASSPILL', description: 'capture / continuity' }),
+  Object.freeze({ value: 'zasselection', label: 'ZASSELECTION', description: 'compare / decide' }),
+  Object.freeze({ value: 'zassimple', label: 'ZASSIMPLE', description: 'design / execute' }),
+  Object.freeze({ value: 'zass', label: 'FULL ZASS', description: 'governed architecture' })
+]);
+
+export const LANGUAGE_CHOICES = Object.freeze([
+  Object.freeze({ value: 'en', label: 'English' }),
+  Object.freeze({ value: 'my', label: 'Bahasa Melayu' })
+]);
+
+const METHODS = Object.freeze({
+  zasspill: Object.freeze({
+    value: 'zasspill',
+    label: 'ZASSPILL',
+    templates: Object.freeze({ en: 'zasspill/en.md', my: 'zasspill/my.md' }),
+    outputs: Object.freeze({ en: 'ZASSPILL_EN.md', my: 'ZASSPILL_MY.md' })
+  }),
+  zasselection: Object.freeze({
+    value: 'zasselection',
+    label: 'ZASSELECTION',
+    templates: Object.freeze({ en: 'zasselection/en.md', my: 'zasselection/my.md' }),
+    outputs: Object.freeze({ en: 'ZASSELECTION_EN.md', my: 'ZASSELECTION_MY.md' })
+  }),
+  zassimple: Object.freeze({
+    value: 'zassimple',
+    label: 'ZASSIMPLE',
+    templates: Object.freeze({ en: 'zassimple/en.md', my: 'zassimple/my.md' }),
+    outputs: Object.freeze({ en: 'ZASSIMPLE_EN.md', my: 'ZASSIMPLE_MY.md' })
+  }),
+  zass: Object.freeze({
+    value: 'zass',
+    label: 'FULL ZASS',
+    templates: Object.freeze({ en: 'zass/en.md', my: 'zass/my.md' }),
+    outputs: Object.freeze({ en: 'ZASS.md', my: 'ZASS.md' })
+  })
+});
+
+const LANGUAGES = Object.freeze({
+  en: Object.freeze({ value: 'en', label: 'English' }),
+  my: Object.freeze({ value: 'my', label: 'Bahasa Melayu' })
+});
+
+export function isSupportedMethod(method) {
+  return Object.hasOwn(METHODS, method);
+}
+
+export function isSupportedLanguage(language) {
+  return Object.hasOwn(LANGUAGES, language);
+}
+
+export function getMethodDescriptor(method) {
+  return METHODS[method] ?? null;
+}
+
+export function getLanguageDescriptor(language) {
+  return LANGUAGES[language] ?? null;
+}
+
+export function getBootstrapDescriptor(method, language) {
+  const methodDescriptor = getMethodDescriptor(method);
+  const languageDescriptor = getLanguageDescriptor(language);
+  const template = methodDescriptor?.templates?.[language];
+  const methodFile = methodDescriptor?.outputs?.[language];
+
+  if (!methodDescriptor || !languageDescriptor || !template || !methodFile) {
+    return null;
+  }
+
+  return Object.freeze({
+    method,
+    language,
+    methodLabel: methodDescriptor.label,
+    languageLabel: languageDescriptor.label,
+    template,
+    methodFile
+  });
+}

package/vendor/bootstrap-core/src/index.js

@@ -0,0 +1,9 @@
+export {
+  CORE_CONTRACT_VERSION,
+  METHOD_CHOICES,
+  LANGUAGE_CHOICES,
+  getBootstrapDescriptor
+} from './catalog.js';
+
+export { buildBootstrapPlan } from './plan.js';
+export { verifyBootstrapSnapshot } from './verify.js';

package/vendor/bootstrap-core/src/plan.js

@@ -0,0 +1,64 @@
+import { CORE_CONTRACT_VERSION, getBootstrapDescriptor } from './catalog.js';
+import { buildProjectReadme, GITIGNORE_CONTENT } from './readme.js';
+import { loadBootstrapTemplate } from './templates.js';
+import { validateBootstrapInput, validateBootstrapPlan } from './validation.js';
+
+export async function buildBootstrapPlan({ projectName, method, language }) {
+  const input = validateBootstrapInput({ projectName, method, language });
+  if (!input.ok) {
+    const error = new Error(input.errors.map((entry) => entry.message).join('; '));
+    error.name = 'BootstrapCoreInputError';
+    error.errors = input.errors;
+    throw error;
+  }
+
+  const descriptor = getBootstrapDescriptor(method, language);
+  const methodContent = await loadBootstrapTemplate(method, language);
+  const readmeContent = buildProjectReadme({
+    projectName,
+    methodLabel: descriptor.methodLabel,
+    methodFile: descriptor.methodFile,
+    language
+  });
+
+  const plan = {
+    contractVersion: CORE_CONTRACT_VERSION,
+    project: {
+      name: projectName,
+      method,
+      language,
+      methodFile: descriptor.methodFile
+    },
+    files: [
+      {
+        path: descriptor.methodFile,
+        role: 'method',
+        content: methodContent
+      },
+      {
+        path: 'README.md',
+        role: 'readme',
+        content: readmeContent
+      },
+      {
+        path: '.gitignore',
+        role: 'gitignore',
+        content: GITIGNORE_CONTENT
+      }
+    ]
+  };
+
+  const validation = validateBootstrapPlan(plan);
+  if (!validation.ok) {
+    const error = new Error(
+      `Generated bootstrap plan failed validation: ${validation.errors
+        .map((entry) => entry.message)
+        .join('; ')}`
+    );
+    error.name = 'BootstrapCorePlanError';
+    error.errors = validation.errors;
+    throw error;
+  }
+
+  return plan;
+}