create-portfoliable 1.0.3

package/scripts/smoke-initializer.mjs

@@ -0,0 +1,129 @@
+// File: create-portfoliable/scripts/smoke-initializer.mjs
+// Purpose: Smoke-test local initializer output by generating a project and validating built artifacts.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// MARK: PATH CONSTANTS
+// Resolves package root used to execute initializer and downstream build commands.
+const projectRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+// Defines isolated temporary workspace root used by the initializer smoke test.
+const tempRoot = path.join(os.tmpdir(), 'portfoliable-initializer-smoke');
+// Defines output directory where the generated sample app is created.
+const generatedAppDir = path.join(tempRoot, 'my-portfolio');
+
+// MARK: ERROR HANDLING
+// Exits immediately with a prefixed smoke-test failure message.
+function fail(message) {
+  console.error(`[smoke:init] ${message}`);
+  process.exit(1);
+}
+
+// MARK: COMMAND EXECUTION
+// Runs an external command and stops the smoke test if the command exits non-zero.
+function runOrFail(command, args, cwd, env = undefined) {
+  // Executes child commands with inherited IO for transparent diagnostics.
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    env: env ? { ...process.env, ...env } : process.env
+  });
+
+  if (result.status !== 0) {
+    fail(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+// MARK: ASSERTION HELPER
+// Verifies bundle output contains expected markers proving starter template content is present.
+function ensureContains(text, needle, description) {
+  if (!text.includes(needle)) {
+    fail(`Missing expected marker (${description}): ${needle}`);
+  }
+}
+
+// Reads the create runtime dependency value from a generated app package.json.
+function readGeneratedRuntimeDependency(appDir) {
+  // Resolves generated package manifest path.
+  const packageJsonPath = path.join(appDir, 'package.json');
+  // Parses generated package manifest to inspect runtime dependency pin.
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson?.dependencies?.['create-portfoliable'];
+}
+
+// Reads the local package version used as default runtime dependency baseline.
+function readLocalPackageVersion() {
+  // Resolves local create-portfoliable package manifest.
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  // Parses local package manifest and returns semantic version.
+  return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;
+}
+
+// MARK: SMOKE ORCHESTRATION
+// Generates an app from the local initializer, builds it, and validates emitted artifacts/content.
+function main() {
+  console.log('[smoke:init] Preparing temp workspace...');
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+  fs.mkdirSync(tempRoot, { recursive: true });
+
+  // Builds expected default runtime dependency from local package version.
+  const expectedDefaultRuntimeDep = `^${readLocalPackageVersion()}`;
+
+  console.log('[smoke:init] Verifying generated default runtime dependency (no override)...');
+  runOrFail(
+    'node',
+    ['./bin/create-portfoliable.mjs', generatedAppDir, '--no-install', '--no-preview', '--no-interactive'],
+    projectRoot
+  );
+
+  // Ensures scaffolded dependency follows package version when no override is provided.
+  const generatedDefaultDep = readGeneratedRuntimeDependency(generatedAppDir);
+  if (generatedDefaultDep !== expectedDefaultRuntimeDep) {
+    fail(
+      `Unexpected default runtime dependency: expected ${expectedDefaultRuntimeDep}, got ${String(generatedDefaultDep)}`
+    );
+  }
+
+  // Cleans generated app before running existing integration/build path.
+  fs.rmSync(generatedAppDir, { recursive: true, force: true });
+
+  console.log('[smoke:init] Generating app from local initializer...');
+  runOrFail(
+    'node',
+    ['./bin/create-portfoliable.mjs', generatedAppDir, '--no-preview', '--no-interactive'],
+    projectRoot,
+    { PORTFOLIABLE_RUNTIME_DEP: `file:${projectRoot}` }
+  );
+
+  console.log('[smoke:init] Building generated app...');
+  runOrFail('npm', ['run', 'portfoliable-build'], generatedAppDir);
+
+  // Resolves generated build assets directory.
+  const distAssetsDir = path.join(generatedAppDir, 'dist', 'assets');
+  if (!fs.existsSync(distAssetsDir)) {
+    fail('dist/assets not found in generated app build output.');
+  }
+
+  // Reads generated asset filenames.
+  const assets = fs.readdirSync(distAssetsDir);
+
+  // Resolves generated main bundle filename.
+  const mainBundle = assets.find((file) => file.startsWith('index-') && file.endsWith('.js'));
+  if (!mainBundle) {
+    fail('Could not find generated app main bundle (index-*.js).');
+  }
+
+  // Loads generated main bundle text for starter content assertions.
+  const bundleText = fs.readFileSync(path.join(distAssetsDir, mainBundle), 'utf8');
+  ensureContains(bundleText, 'Making Portfoliable', 'starter case title');
+  ensureContains(bundleText, 'Apple MacBook Air M5', 'starter model mapping');
+
+  console.log('[smoke:init] Initializer smoke checks passed.');
+}
+
+main();

package/scripts/smoke-packed.mjs

@@ -0,0 +1,184 @@
+// File: create-portfoliable/scripts/smoke-packed.mjs
+// Purpose: Smoke-test npm-packed initializer artifact by generating and building a consumer app.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// MARK: PATH CONSTANTS
+// Resolves package root used for packing and command execution.
+const projectRoot = path.resolve(path.dirname(new URL(import.meta.url).pathname), '..');
+// Defines isolated temporary root used for packed-artifact smoke runs.
+const tempRoot = path.join(os.tmpdir(), 'portfoliable-packed-smoke');
+// Defines generated application output path.
+const generatedAppDir = path.join(tempRoot, 'my-portfolio');
+
+// MARK: ERROR HANDLING
+// Exits immediately with a prefixed packed-smoke failure message.
+function fail(message) {
+  console.error(`[smoke:packed] ${message}`);
+  process.exit(1);
+}
+
+// MARK: COMMAND EXECUTION HELPERS
+// Runs external commands with inherited IO and fails on non-zero status.
+function runOrFail(command, args, cwd, env = undefined) {
+  // Executes child command with inherited terminal output.
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: 'inherit',
+    shell: process.platform === 'win32',
+    env: env ? { ...process.env, ...env } : process.env
+  });
+
+  if (result.status !== 0) {
+    fail(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+// Runs external commands while capturing stdout/stderr, used for JSON-producing commands.
+function runCaptureOrFail(command, args, cwd) {
+  // Executes command while capturing stdout/stderr for parser use.
+  const result = spawnSync(command, args, {
+    cwd,
+    stdio: ['ignore', 'pipe', 'pipe'],
+    encoding: 'utf8',
+    shell: process.platform === 'win32'
+  });
+
+  if (result.status !== 0) {
+    // Captures stderr text to enrich failure diagnostics.
+    const stderr = (result.stderr || '').trim();
+    fail(`Command failed: ${command} ${args.join(' ')}${stderr ? `\n${stderr}` : ''}`);
+  }
+
+  return (result.stdout || '').trim();
+}
+
+// MARK: ASSERTION HELPER
+// Verifies the generated bundle contains expected content markers.
+function ensureContains(text, needle, description) {
+  if (!text.includes(needle)) {
+    fail(`Missing expected marker (${description}): ${needle}`);
+  }
+}
+
+// Reads create runtime dependency from generated app package.json.
+function readGeneratedRuntimeDependency(appDir) {
+  // Resolves generated package manifest path.
+  const packageJsonPath = path.join(appDir, 'package.json');
+  // Parses generated package manifest to inspect runtime dependency version.
+  const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+  return packageJson?.dependencies?.['create-portfoliable'];
+}
+
+// Reads local package version used as expected default dependency baseline.
+function readLocalPackageVersion() {
+  // Resolves local package manifest.
+  const packageJsonPath = path.join(projectRoot, 'package.json');
+  // Parses package version string from local manifest.
+  return JSON.parse(fs.readFileSync(packageJsonPath, 'utf8')).version;
+}
+
+// MARK: PACK RESOLUTION
+// Builds an npm tarball and resolves the exact file path returned by npm pack.
+function resolveTarballPath() {
+  // Runs npm pack and captures JSON output.
+  const packOutput = runCaptureOrFail('npm', ['pack', '--json'], projectRoot);
+  let parsed;
+
+  try {
+    parsed = JSON.parse(packOutput);
+  } catch {
+    fail(`Could not parse npm pack --json output: ${packOutput}`);
+  }
+
+  // Extracts returned tarball filename from npm pack JSON payload.
+  const filename = parsed?.[0]?.filename;
+  if (!filename) {
+    fail('npm pack did not return a tarball filename.');
+  }
+
+  // Resolves tarball absolute path on disk.
+  const tarballPath = path.join(projectRoot, filename);
+  if (!fs.existsSync(tarballPath)) {
+    fail(`Packed tarball not found: ${tarballPath}`);
+  }
+
+  return tarballPath;
+}
+
+// MARK: SMOKE ORCHESTRATION
+// Packs the artifact, scaffolds an app from that artifact, builds it, and validates outputs.
+function main() {
+  console.log('[smoke:packed] Preparing temp workspace...');
+  fs.rmSync(tempRoot, { recursive: true, force: true });
+  fs.mkdirSync(tempRoot, { recursive: true });
+
+  console.log('[smoke:packed] Packing create-portfoliable...');
+  // Resolves packed tarball path for installer smoke run.
+  const tarballPath = resolveTarballPath();
+  // Builds file: dependency string consumed by npm exec package override.
+  const runtimeDep = `file:${tarballPath}`;
+  // Builds expected default runtime dependency for no-override scaffolding.
+  const expectedDefaultRuntimeDep = `^${readLocalPackageVersion()}`;
+  // Resolves dedicated output path for default-no-override validation.
+  const generatedDefaultAppDir = path.join(tempRoot, 'my-portfolio-default');
+
+  try {
+    console.log('[smoke:packed] Verifying generated default runtime dependency (no override)...');
+    runOrFail(
+      'npm',
+      ['exec', '--yes', `--package=${runtimeDep}`, 'create', generatedDefaultAppDir, '--', '--no-install', '--no-preview'],
+      tempRoot
+    );
+
+    // Ensures packed initializer default dependency tracks packaged version.
+    const generatedDefaultDep = readGeneratedRuntimeDependency(generatedDefaultAppDir);
+    if (generatedDefaultDep !== expectedDefaultRuntimeDep) {
+      fail(
+        `Unexpected default runtime dependency: expected ${expectedDefaultRuntimeDep}, got ${String(generatedDefaultDep)}`
+      );
+    }
+
+    console.log('[smoke:packed] Generating app from packed artifact...');
+    runOrFail(
+      'npm',
+      ['exec', '--yes', `--package=${runtimeDep}`, 'create', generatedAppDir, '--', '--no-preview'],
+      tempRoot,
+      { PORTFOLIABLE_RUNTIME_DEP: runtimeDep }
+    );
+
+    console.log('[smoke:packed] Building generated app...');
+    runOrFail('npm', ['run', 'portfoliable-build'], generatedAppDir);
+
+    // Resolves generated dist assets directory.
+    const distAssetsDir = path.join(generatedAppDir, 'dist', 'assets');
+    if (!fs.existsSync(distAssetsDir)) {
+      fail('dist/assets not found in generated app build output.');
+    }
+
+    // Reads generated asset filenames.
+    const assets = fs.readdirSync(distAssetsDir);
+
+    // Resolves generated main bundle filename.
+    const mainBundle = assets.find((file) => file.startsWith('index-') && file.endsWith('.js'));
+    if (!mainBundle) {
+      fail('Could not find generated app main bundle (index-*.js).');
+    }
+
+    // Loads generated main bundle text for assertions.
+    const bundleText = fs.readFileSync(path.join(distAssetsDir, mainBundle), 'utf8');
+    ensureContains(bundleText, 'Making Portfoliable', 'starter case title');
+    ensureContains(bundleText, 'Apple MacBook Air M5', 'starter model mapping');
+
+    console.log('[smoke:packed] Packed-artifact smoke checks passed.');
+  } finally {
+    fs.rmSync(tarballPath, { force: true });
+  }
+}
+
+main();

package/scripts/switch-valence-source.mjs

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+// File: scripts/switch-valence-source.mjs
+// Purpose: Switch installed valence source between declared npm range and local workspace path.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// MARK: MODE CONFIGURATION
+const VALID_MODES = new Set(['status', 'local', 'npm']);
+
+// MARK: PROCESS HELPERS
+// Prints an error and exits immediately for invalid script states.
+function fail(message) {
+  console.error(message);
+  process.exit(1);
+}
+
+// Runs a child process command and fails fast when the command exits non-zero.
+function run(command, args) {
+  const result = spawnSync(command, args, { stdio: 'inherit' });
+  if (result.status !== 0) {
+    fail(`Command failed: ${command} ${args.join(' ')}`);
+  }
+}
+
+// Reads and parses a JSON file with standardized error reporting.
+function readJson(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (error) {
+    fail(`Failed to read JSON file: ${filePath}\n${error.message}`);
+  }
+}
+
+// Reads declared valence dependency range from repository package metadata.
+function getDeclaredRange(repoRoot) {
+  const pkg = readJson(path.join(repoRoot, 'package.json'));
+  const range = pkg?.dependencies?.['@portfoliablejs/valence'];
+  if (!range) {
+    fail('Missing dependency declaration for @portfoliablejs/valence in package.json');
+  }
+  return range;
+}
+
+// Detects currently installed valence mode (missing, npm package, or local link).
+function getInstalledState(repoRoot) {
+  const modulePath = path.join(repoRoot, 'node_modules', '@portfoliable', 'valence');
+
+  if (!fs.existsSync(modulePath)) {
+    return {
+      installed: false,
+      mode: 'missing',
+      version: null,
+      symlinkTarget: null,
+    };
+  }
+
+  const stat = fs.lstatSync(modulePath);
+  const symlinkTarget = stat.isSymbolicLink() ? fs.readlinkSync(modulePath) : null;
+  const packageJsonPath = path.join(modulePath, 'package.json');
+  const version = fs.existsSync(packageJsonPath) ? readJson(packageJsonPath).version : null;
+
+  return {
+    installed: true,
+    mode: stat.isSymbolicLink() ? 'local-link' : 'npm-package',
+    version,
+    symlinkTarget,
+  };
+}
+
+// Warns when required template exports are missing from installed valence source.
+function warnIfTemplateExportsMissing(repoRoot) {
+  const mainPath = path.join(repoRoot, 'node_modules', '@portfoliable', 'valence', 'src', 'main.js');
+  if (!fs.existsSync(mainPath)) return;
+
+  const source = fs.readFileSync(mainPath, 'utf8');
+  const hasHomeViewExport = source.includes("./stories/templates/HomeView/HomeView.js");
+  const hasPlayerViewExport = source.includes("./stories/templates/PlayerView/PlayerView.js");
+
+  if (hasHomeViewExport && hasPlayerViewExport) return;
+
+  console.warn('warning: installed @portfoliablejs/valence package is missing template exports required by create-portfoliable runtime (HomeView/PlayerView).');
+  console.warn('warning: use npm run valence:local while developing until a published Valence version includes template exports.');
+}
+
+// Prints declared dependency and currently installed valence status information.
+function printStatus(repoRoot, declaredRange) {
+  const installed = getInstalledState(repoRoot);
+
+  console.log(`declared range: ${declaredRange}`);
+  if (!installed.installed) {
+    console.log('installed: no');
+    return;
+  }
+
+  console.log(`installed: yes (${installed.mode})`);
+  if (installed.version) {
+    console.log(`installed version: ${installed.version}`);
+  }
+  if (installed.symlinkTarget) {
+    console.log(`local link target: ${installed.symlinkTarget}`);
+  }
+
+  warnIfTemplateExportsMissing(repoRoot);
+}
+
+// MARK: SOURCE SWITCH OPERATIONS
+// Installs valence from a local filesystem path and refreshes compatibility assets.
+function switchToLocal(repoRoot) {
+  const localInput = process.env.VALENCE_LOCAL_PATH || '../../valence';
+  const localPath = path.resolve(repoRoot, localInput);
+  const localPackageJsonPath = path.join(localPath, 'package.json');
+
+  if (!fs.existsSync(localPackageJsonPath)) {
+    fail(`Could not find valence package.json at: ${localPackageJsonPath}`);
+  }
+
+  const localPkg = readJson(localPackageJsonPath);
+  if (localPkg.name !== '@portfoliablejs/valence') {
+    fail(`Expected package name @portfoliablejs/valence at ${localPackageJsonPath}, found ${localPkg.name || '(missing)'}`);
+  }
+
+  run('npm', ['install', `@portfoliablejs/valence@file:${localPath}`, '--no-save']);
+  run('npm', ['run', 'ensure:valence']);
+}
+
+// Installs valence from the declared npm range and refreshes compatibility assets.
+function switchToNpm(declaredRange) {
+  run('npm', ['install', `@portfoliablejs/valence@${declaredRange}`, '--no-save']);
+  run('npm', ['run', 'ensure:valence']);
+}
+
+// MARK: SCRIPT ENTRYPOINT
+// Routes CLI mode selection for status reporting and source switching.
+function main() {
+  const mode = process.argv[2] || 'status';
+  if (!VALID_MODES.has(mode)) {
+    fail('Usage: node ./scripts/switch-valence-source.mjs [status|local|npm]');
+  }
+
+  const repoRoot = process.cwd();
+  const declaredRange = getDeclaredRange(repoRoot);
+
+  if (mode === 'status') {
+    printStatus(repoRoot, declaredRange);
+    return;
+  }
+
+  if (mode === 'local') {
+    switchToLocal(repoRoot);
+    printStatus(repoRoot, declaredRange);
+    return;
+  }
+
+  switchToNpm(declaredRange);
+  printStatus(repoRoot, declaredRange);
+}
+
+main();

package/scripts/sync-template-shared.mjs

@@ -0,0 +1,136 @@
+#!/usr/bin/env node
+// File: scripts/sync-template-shared.mjs
+// Purpose: Keep selected initializer template files synchronized with canonical root sources.
+// Author: Lio Schimanko
+
+// MARK: IMPORTS
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// MARK: PATH CONSTANTS
+// Resolves this script directory path.
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+// Resolves package root used to resolve mapped source/target files.
+const repoRoot = path.resolve(__dirname, '..');
+
+// MARK: TEMPLATE HEADER
+// Defines template parser header injected into synchronized parser target file.
+const TEMPLATE_PARSER_HEADER = [
+  '// File: create-portfoliable/templates/src/parser/markdown.js',
+  '// Purpose: Parse template markdown cases into normalized case data.',
+  '// Author: Lio Schimanko',
+  '// Note: Auto-synced from src/parser/markdown.js. Edit the canonical source only.',
+  ''
+].join('\n');
+
+// MARK: SYNC MAPPINGS
+// Lists source/target mapping definitions and optional transform functions.
+const mappings = [
+  {
+    source: 'src/parser/markdown.js',
+    target: 'templates/src/parser/markdown.js',
+    // Removes source header and injects template-specific header contract.
+    transform: (sourceText) => {
+      // Splits source into lines for header detection.
+      const lines = sourceText.split('\n');
+      // Tracks start index for parser body after optional 3-line header.
+      let bodyStart = 0;
+
+      if (
+        lines[0]?.startsWith('// File:')
+        && lines[1]?.startsWith('// Purpose:')
+        && lines[2]?.startsWith('// Author:')
+      ) {
+        bodyStart = lines[3] === '' ? 4 : 3;
+      }
+
+      // Extracts parser body and strips leading blank lines.
+      const body = lines.slice(bodyStart).join('\n').replace(/^\n+/, '');
+      return `${TEMPLATE_PARSER_HEADER}${body}`;
+    }
+  }
+];
+
+// Resolves repository-relative path to absolute path.
+function resolveRepoPath(relPath) {
+  return path.resolve(repoRoot, relPath);
+}
+
+// Reads UTF-8 file content.
+function readUtf8(filePath) {
+  return fs.readFileSync(filePath, 'utf8');
+}
+
+// Writes UTF-8 file content, creating parent directories when needed.
+function writeUtf8(filePath, content) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, content, 'utf8');
+}
+
+// Normalizes EOL format to LF for reliable cross-platform comparisons.
+function normalizeEol(text) {
+  return text.replace(/\r\n/g, '\n');
+}
+
+// Executes one mapping sync action in check or write mode.
+function syncOne(mapping, mode) {
+  // Resolves mapped source path.
+  const sourcePath = resolveRepoPath(mapping.source);
+  // Resolves mapped target path.
+  const targetPath = resolveRepoPath(mapping.target);
+  // Reads source file text.
+  const sourceText = readUtf8(sourcePath);
+  // Applies optional transform to source text.
+  const expectedText = mapping.transform ? mapping.transform(sourceText) : sourceText;
+  // Normalizes expected text for comparison.
+  const expectedNormalized = normalizeEol(expectedText);
+
+  // Reads current target file text when present.
+  const currentText = fs.existsSync(targetPath) ? readUtf8(targetPath) : '';
+  // Normalizes current target text for comparison.
+  const currentNormalized = normalizeEol(currentText);
+  // Determines whether target file already matches expected content.
+  const isSynced = expectedNormalized === currentNormalized;
+
+  if (mode === 'check') {
+    if (!isSynced) {
+      console.error(`[sync:templates] Drift detected: ${mapping.target}`);
+      console.error(`[sync:templates] Canonical source: ${mapping.source}`);
+      return false;
+    }
+    console.log(`[sync:templates] OK: ${mapping.target}`);
+    return true;
+  }
+
+  if (!isSynced) {
+    writeUtf8(targetPath, expectedText.endsWith('\n') ? expectedText : `${expectedText}\n`);
+    console.log(`[sync:templates] Updated: ${mapping.target}`);
+  } else {
+    console.log(`[sync:templates] Unchanged: ${mapping.target}`);
+  }
+
+  return true;
+}
+
+// MARK: SCRIPT ENTRYPOINT
+// Runs all mappings in check or write mode and exits non-zero on drift.
+function main() {
+  // Parses CLI args used to switch between check and write mode.
+  const args = new Set(process.argv.slice(2));
+  // Resolves operating mode from CLI flags.
+  const mode = args.has('--check') ? 'check' : 'write';
+
+  // Runs sync/check for each configured mapping.
+  const results = mappings.map((mapping) => syncOne(mapping, mode));
+  // Aggregates overall success result.
+  const ok = results.every(Boolean);
+
+  if (!ok) {
+    console.error('[sync:templates] Template files are out of sync. Run: npm run sync:templates');
+    process.exit(1);
+  }
+}
+
+// Executes sync script main function.
+main();