@cratis/create-cast 0.0.1 → 0.1.0

package/README.md

@@ -1,3 +1,9 @@
 # @cratis/create-cast
 
-Placeholder that reserves the package name for [Cratis Cast](https://github.com/Cratis/Cast). The first release is coming; do not install this version.
+Creates a [Cratis Cast](https://cast.cratis.io) site from your public GitHub profile.
+
+```sh
+npm create @cratis/cast@latest my-site -- --github your-login
+```
+
+Options: `[directory]`, `--github <login>`, `--domain <domain>`, `--yes`, `--help`. See [getting started](https://github.com/Cratis/Cast/blob/main/Documentation/getting-started.md).

package/dist/PublicProfile.js

@@ -0,0 +1,3 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export {};

package/dist/ScaffoldInput.js

@@ -0,0 +1,3 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+export {};

package/dist/castYaml.js

@@ -0,0 +1,131 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/** A YAML double-quoted scalar. JSON strings are valid YAML. */
+const quote = (value) => JSON.stringify(value);
+/** The public URL the site will have: the custom domain, or the user's GitHub Pages address. */
+export const siteUrl = (input) => input.domain ? `https://${input.domain}` : `https://${input.profile.login.toLowerCase()}.github.io`;
+/** cast.yaml: prefilled from the public profile, with a commented example for every section. */
+export function castYaml(input) {
+    const { profile } = input;
+    const name = profile.name ?? profile.login;
+    const firstLine = profile.bio?.split(/(?<=[.!?])\s/)[0];
+    const lines = [
+        '# yaml-language-server: $schema=https://unpkg.com/@cratis/cast/cast.schema.json',
+        '#',
+        '# Your Cast site. Every page is built from this file; edit it and the site follows.',
+        '# Text fields can use *emphasis* (the italic serif accent), **strong**, `code` and [links](https://example.com).',
+        '# Reference: https://github.com/Cratis/Cast/blob/main/Documentation/cast-yaml.md',
+        '',
+        'site:',
+        `  url: ${quote(siteUrl(input))}`,
+        '  # description: One sentence for search engines; defaults to your tagline and intro.',
+        '  # source: https://github.com/you/your-site',
+        '',
+        'person:',
+        `  name: ${quote(name)}`,
+        `  handle: ${quote(profile.login)}`,
+        `  title: ${quote(firstLine ?? 'Software engineer')}   # the role line under your name`,
+        ...(profile.location ? [`  location: ${quote(profile.location)}`] : ['  # location: Oslo, Norway']),
+        '  # email: you@example.com',
+        ...(profile.avatarUrl ? [`  photo: ${quote(profile.avatarUrl)}   # or a local file such as ./avatar.jpeg`] : ['  # photo: ./avatar.jpeg']),
+        '  links:',
+        `    github: ${quote(`https://github.com/${profile.login}`)}`,
+        ...(profile.blog && /linkedin\.com/i.test(profile.blog) ? [`    linkedin: ${quote(profile.blog)}`] : []),
+        ...(profile.blog && !/linkedin\.com/i.test(profile.blog) ? [`    website: ${quote(profile.blog)}`, '    # linkedin: https://www.linkedin.com/in/you/'] : []),
+        ...(!profile.blog ? ['    # linkedin: https://www.linkedin.com/in/you/'] : []),
+        '  tagline: "I build software that *remembers.*"   # the hero headline; *asterisks* mark the accent',
+        `  intro: ${quote(profile.bio ?? 'One paragraph about what you build and why. Keep it specific.')}`,
+        '  # about:',
+        '  #   - A paragraph for the "about" column and the CV summary.',
+        '  # interests: [Event Modeling, Event Sourcing, Developer experience]',
+        '  # languages: [English (fluent)]',
+        '',
+        '# The "now" read model: ordered rows. YYYY-MM values show as months.',
+        '# now:',
+        '#   role: Senior Engineer',
+        '#   company: Example Co',
+        '#   since: 2025-06',
+        '#   building: [Something with Cratis]',
+        '',
+        '# Big numbers. `live` replaces the value with a build-time figure from GitHub.',
+        '# stats:',
+        '#   - { value: 1000, suffix: "+", label: contributions on GitHub in the last year, live: contributionsLastYear }',
+        '#   - { value: 10, suffix: "+", label: merged PRs in the Cratis org, live: mergedPullRequests }',
+        '',
+        '# Your career as an event stream. Types are past-tense PascalCase. `role` sets the current role;',
+        '# `endsRole` closes the open role at that organization. The page replays these in order.',
+        '# career:',
+        '#   events:',
+        '#     - date: 2018-07',
+        '#       type: EmploymentStarted',
+        '#       title: Software Engineer',
+        '#       org: Example Co',
+        '#       orgUrl: https://example.com',
+        '#       role: Software Engineer',
+        '#       summary: What you built and what changed because of it.',
+        '#       skills: [C#, Event Sourcing]',
+        '#     - date: 2024-06',
+        '#       type: TalkGiven',
+        '#       title: "Talk: Event Modeling in practice"',
+        '#       summary: Where and what about.',
+        '',
+        '# What you do at Cratis. The section only renders when this key is present.',
+        '# cratis:',
+        '#   role: I maintain the Chronicle Go client and help teams adopt event modeling.',
+        '#   repos:',
+        '#     - { name: Chronicle.Go, url: https://github.com/Cratis/Chronicle.Go, kind: Client · Go, group: client, desc: Idiomatic Go client for Chronicle. }',
+        '#   highlights: [A change you landed that you are proud of]',
+        '',
+        '# projects:',
+        '#   - name: my-tool',
+        '#     url: https://github.com/you/my-tool',
+        '#     category: cli',
+        '#     pitch: What it does, in one sentence.',
+        '#     features: [One, Two, Three]',
+        '#     stack: [Rust]',
+        '#     install: brew install you/tap/my-tool',
+        '# projectCategories:',
+        '#   - { id: cli, label: CLI }',
+        '',
+        '# talks:',
+        '#   - { title: Event sourcing in practice, host: Example Meetup, date: 2025-11-12, url: https://example.com/talk, summary: What it covered. }',
+        '# community:',
+        '#   - { title: Event Modeling Conference, detail: Attended, date: 2025-10 }',
+        '',
+        '# Posts from RSS/Atom feeds or a Starlight Blog author page (such as blog.cratis.io).',
+        '# writing:',
+        '#   sources:',
+        '#     - rss: https://example.com/rss.xml',
+        '#     - starlightBlogAuthor: https://blog.cratis.io/authors/your-name/',
+        '#   themes:',
+        '#     - { id: event-sourcing, label: Event sourcing, tags: [event-sourcing, cqrs] }',
+        '',
+        '# agentic:',
+        '#   pitch: How you work with AI coding agents.',
+        '#   items:',
+        '#     - { name: my-setup, url: https://github.com/you/my-setup, kind: Agent configuration, text: What it is. }',
+        '',
+        '# skills:',
+        '#   Languages: [C#, TypeScript]',
+        '#   Architecture: [Event Modeling, Event Sourcing, CQRS]',
+        '# education:',
+        '#   - { degree: Bachelor of Computer Science, school: Example University, from: "2015", to: "2018" }',
+        '# certifications:',
+        '#   - { title: Example certificate, issuer: Example, year: "2023" }',
+        '',
+        '# Public GitHub data captured at build time (a token is read from GITHUB_TOKEN or GH_TOKEN).',
+        'github:',
+        '  orgs: [Cratis]   # organizations whose merged public pull requests you want counted',
+        '  # releases: [you/my-tool]   # latest release versions your projects',
+        '  # stars: [Cratis/Chronicle]',
+        '',
+        'theme:',
+        '  accent: "#8b5cf6"   # your accent; Cratis violet by default',
+        '  mode: dark          # dark, light or system for first-time visitors',
+        '',
+        '# Section order. Leave it out to show every section that has data.',
+        '# sections: [hero, now, stats, career, cratis, activity, projects, writing, talks, skills, contact]',
+        '',
+    ];
+    return lines.join('\n');
+}

package/dist/fetchProfile.js

@@ -0,0 +1,31 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+const clean = (value) => (value && value.trim() ? value.trim() : undefined);
+/** Reads a public GitHub profile. Without network or for an unknown login it returns just the login. */
+export async function fetchProfile(login, fetchImplementation = fetch) {
+    const token = process.env.GITHUB_TOKEN || process.env.GH_TOKEN;
+    try {
+        const response = await fetchImplementation(`https://api.github.com/users/${encodeURIComponent(login)}`, {
+            headers: { accept: 'application/vnd.github+json', 'user-agent': 'cratis-create-cast', ...(token ? { authorization: `bearer ${token}` } : {}) },
+            signal: AbortSignal.timeout(8000),
+        });
+        if (!response.ok)
+            return { profile: { login }, found: false };
+        const user = await response.json();
+        const blog = clean(user.blog);
+        return {
+            found: true,
+            profile: {
+                login: clean(user.login) ?? login,
+                ...(clean(user.name) ? { name: clean(user.name) } : {}),
+                ...(clean(user.bio) ? { bio: clean(user.bio) } : {}),
+                ...(clean(user.location) ? { location: clean(user.location) } : {}),
+                ...(blog ? { blog: /^https?:\/\//.test(blog) ? blog : `https://${blog}` } : {}),
+                ...(clean(user.avatar_url) ? { avatarUrl: clean(user.avatar_url) } : {}),
+            },
+        };
+    }
+    catch {
+        return { profile: { login }, found: false };
+    }
+}

package/dist/generateFiles.js

@@ -0,0 +1,133 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { castYaml, siteUrl } from './castYaml.js';
+/** A package name npm accepts, derived from the directory name. */
+export const packageName = (directory) => directory.split(/[\\/]/).filter(Boolean).pop().toLowerCase().replace(/[^a-z0-9._-]+/g, '-').replace(/^[._-]+|[._-]+$/g, '') || 'cast-site';
+const packageJson = (input) => `${JSON.stringify({
+    name: packageName(input.directory),
+    version: '0.0.0',
+    private: true,
+    type: 'module',
+    description: `${input.profile.name ?? input.profile.login}'s Cast site.`,
+    scripts: {
+        dev: 'astro dev',
+        build: 'astro build',
+        preview: 'astro preview',
+    },
+    engines: { node: '>=23.0.0' },
+    dependencies: {
+        '@cratis/cast': input.castVersion,
+        astro: '^7.2.0',
+    },
+}, null, 2)}\n`;
+const astroConfig = `import cast from '@cratis/cast';
+import { defineConfig } from 'astro/config';
+
+// cast() reads ./cast.yaml, captures public GitHub data at build time and adds every page.
+export default defineConfig({
+    integrations: [cast()],
+});
+`;
+const workflow = `name: Build and deploy Cast site
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+  # Hourly rebuild keeps the public GitHub numbers, the feed and the Cast badge current.
+  schedule:
+    - cron: '23 * * * *'
+  workflow_dispatch:
+
+# Least privilege by default; only the deploy job can write to Pages.
+permissions:
+  contents: read
+
+concurrency:
+  group: \${{ github.event_name == 'pull_request' && format('pr-{0}', github.event.pull_request.number) || 'pages' }}
+  cancel-in-progress: \${{ github.event_name == 'pull_request' }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 23.x
+      - name: Install
+        run: if [ -f package-lock.json ]; then npm ci; else npm install --no-audit --no-fund; fi
+      - name: Build
+        run: npm run build
+        env:
+          # Read-only: Cast captures public GitHub data at build time and never fails the build on it.
+          GITHUB_TOKEN: \${{ secrets.GITHUB_TOKEN }}
+      - name: Upload artifact
+        if: github.event_name != 'pull_request'
+        uses: actions/upload-pages-artifact@v3
+        with:
+          path: ./dist
+
+  deploy:
+    if: github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    permissions:
+      pages: write
+      id-token: write
+    steps:
+      - name: Deploy to GitHub Pages
+        id: deployment
+        uses: actions/deploy-pages@v4
+`;
+const gitignore = `node_modules/
+dist/
+.astro/
+.DS_Store
+# .cast/snapshot.json is the last good GitHub data. Commit it so builds without a token still show numbers.
+`;
+const readme = (input) => `# ${input.profile.name ?? input.profile.login}
+
+My [Cratis Cast](https://cast.cratis.io) site: one [\`cast.yaml\`](cast.yaml), built with [@cratis/cast](https://github.com/Cratis/Cast).
+
+## Next steps
+
+1. Install and run it:
+
+   \`\`\`sh
+   npm install
+   npm run dev        # http://localhost:4321
+   \`\`\`
+
+2. Fill in [\`cast.yaml\`](cast.yaml). Every section has a commented example; uncomment what you want. Your editor completes fields from the schema.
+3. Build with live GitHub numbers (optional locally, automatic in CI):
+
+   \`\`\`sh
+   GITHUB_TOKEN=$(gh auth token) npm run build
+   \`\`\`
+
+4. Push to GitHub and turn on Pages: **Settings → Pages → Source: GitHub Actions**. The workflow in [\`.github/workflows/publish.yaml\`](.github/workflows/publish.yaml) builds on every push and every hour.
+${input.domain ? `5. Point the DNS for \`${input.domain}\` at GitHub Pages; [\`public/CNAME\`](public/CNAME) already names it.\n` : ''}
+The site will be at ${siteUrl(input)}.
+
+## Your badge
+
+Your site shows the Cast tier its build resolved, as a claim: Core and Partner from the [Cast registry](https://github.com/Cratis/Cast/blob/main/Registry/README.md), Contributor from merged public pull requests in the Cratis organization. The directory, built by Cratis, is the source of truth; link to your verification page: https://cast.cratis.io/${input.profile.login.toLowerCase()}
+`;
+/** Every file of a new Cast site, by relative path. */
+export function generateFiles(input) {
+    return {
+        'cast.yaml': castYaml(input),
+        'package.json': packageJson(input),
+        'astro.config.mjs': astroConfig,
+        '.github/workflows/publish.yaml': workflow,
+        '.gitignore': gitignore,
+        'README.md': readme(input),
+        ...(input.domain ? { 'public/CNAME': `${input.domain}\n` } : {}),
+    };
+}

package/dist/index.js

@@ -0,0 +1,78 @@
+#!/usr/bin/env node
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { createInterface } from 'node:readline/promises';
+import { fileURLToPath } from 'node:url';
+import { fetchProfile } from './fetchProfile.js';
+import { generateFiles } from './generateFiles.js';
+import { parseArguments } from './parseArguments.js';
+const usage = `Create a Cratis Cast site.
+
+Usage:
+  npm create @cratis/cast@latest [directory] -- [--github <login>] [--domain <domain>] [--yes]
+  yarn create @cratis/cast [directory] [--github <login>] [--domain <domain>] [--yes]
+
+Options:
+  --github <login>   Your GitHub login. Prefills cast.yaml from your public profile.
+  --domain <domain>  Custom domain, for example www.example.com. Writes public/CNAME.
+  --yes, -y          Do not ask; use the options given and defaults for the rest.
+  --help, -h         Show this help.
+`;
+const ownVersion = () => {
+    const packageFile = fileURLToPath(new URL('../package.json', import.meta.url));
+    return JSON.parse(readFileSync(packageFile, 'utf8')).version;
+};
+const isEmptyDirectory = (directory) => !existsSync(directory) || readdirSync(directory).filter(entry => entry !== '.git').length === 0;
+async function main() {
+    const options = parseArguments(process.argv.slice(2));
+    if (options.help) {
+        process.stdout.write(usage);
+        return 0;
+    }
+    const interactive = !options.yes && process.stdin.isTTY === true;
+    const prompt = interactive ? createInterface({ input: process.stdin, output: process.stdout }) : undefined;
+    const ask = async (question, fallback) => {
+        if (!prompt)
+            return fallback;
+        const answer = (await prompt.question(`${question}${fallback ? ` (${fallback})` : ''}: `)).trim();
+        return answer || fallback;
+    };
+    try {
+        const github = options.github ?? await ask('Your GitHub login', '');
+        if (!github || !/^[A-Za-z0-9-]+$/.test(github)) {
+            process.stderr.write('A GitHub login is needed: pass --github <login>.\n');
+            return 1;
+        }
+        const directory = options.directory ?? await ask('Directory for the site', `${github.toLowerCase()}-cast`);
+        const domain = options.domain ?? (await ask('Custom domain (leave empty for GitHub Pages)', '') || undefined);
+        const target = path.resolve(directory);
+        if (!isEmptyDirectory(target)) {
+            process.stderr.write(`${target} is not empty. Choose a new or empty directory.\n`);
+            return 1;
+        }
+        process.stdout.write(`Reading the public GitHub profile of ${github}...\n`);
+        const { profile, found } = await fetchProfile(github);
+        if (!found)
+            process.stdout.write('Could not read the profile (offline or unknown login); cast.yaml gets placeholders instead.\n');
+        const files = generateFiles({ directory, profile, domain, castVersion: `^${ownVersion()}` });
+        for (const [relative, content] of Object.entries(files)) {
+            const file = path.join(target, relative);
+            await mkdir(path.dirname(file), { recursive: true });
+            await writeFile(file, content);
+        }
+        const relative = path.relative(process.cwd(), target);
+        const shown = relative === '' ? '.' : relative.startsWith('..') ? target : relative;
+        process.stdout.write(`\nYour Cast site is in ${shown}.\n\nNext:\n  cd ${shown}\n  npm install\n  npm run dev\n\nThen fill in cast.yaml. The README lists how to publish it.\n`);
+        return 0;
+    }
+    finally {
+        prompt?.close();
+    }
+}
+main().then(code => process.exit(code), error => {
+    process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/parseArguments.js

@@ -0,0 +1,33 @@
+// Copyright (c) Cratis. All rights reserved.
+// Licensed under the MIT license. See LICENSE file in the project root for full license information.
+/** Parses `[dir] [--github <login>] [--domain <domain>] [--yes] [--help]`; `--flag=value` works too. */
+export function parseArguments(argv) {
+    const result = { yes: false, help: false };
+    for (let index = 0; index < argv.length; index++) {
+        const argument = argv[index];
+        const [flag, inline] = argument.startsWith('--') ? argument.split(/=(.*)/s, 2) : [argument, undefined];
+        const value = () => inline ?? argv[++index];
+        switch (flag) {
+            case '--github':
+                result.github = value();
+                break;
+            case '--domain':
+                result.domain = value();
+                break;
+            case '--yes':
+            case '-y':
+                result.yes = true;
+                break;
+            case '--help':
+            case '-h':
+                result.help = true;
+                break;
+            default:
+                if (!argument.startsWith('-') && result.directory === undefined)
+                    result.directory = argument;
+                else
+                    throw new Error(`Unknown option '${argument}'. Run with --help for usage.`);
+        }
+    }
+    return result;
+}

package/package.json

@@ -1,9 +1,45 @@
 {
-  "name": "@cratis/create-cast",
-  "version": "0.0.1",
-  "description": "Placeholder for Cratis Cast. The first release is coming; see https://github.com/Cratis/Cast",
-  "license": "MIT",
-  "repository": { "type": "git", "url": "git+https://github.com/Cratis/Cast.git" },
-  "homepage": "https://github.com/Cratis/Cast",
-  "files": ["README.md"]
-}
+    "name": "@cratis/create-cast",
+    "version": "0.1.0",
+    "description": "npm create @cratis/cast: scaffold a Cratis Cast profile site from your GitHub profile.",
+    "keywords": [
+        "cratis",
+        "cast",
+        "create",
+        "astro",
+        "portfolio",
+        "cv"
+    ],
+    "author": "Cratis",
+    "license": "MIT",
+    "homepage": "https://cast.cratis.io/join",
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/Cratis/Cast.git",
+        "directory": "Source/CreateCast"
+    },
+    "publishConfig": {
+        "access": "public"
+    },
+    "type": "module",
+    "engines": {
+        "node": ">=23.0.0"
+    },
+    "bin": "dist/index.js",
+    "files": [
+        "dist",
+        "!dist/**/for_*/**",
+        "!dist/**/*.map"
+    ],
+    "scripts": {
+        "clean": "yarn g:clean",
+        "build": "yarn g:tsc -p tsconfig.build.json && chmod +x dist/index.js",
+        "lint": "yarn g:lint",
+        "lint:ci": "yarn g:lint:ci",
+        "test": "yarn g:test",
+        "ci": "yarn g:ci"
+    },
+    "devDependencies": {
+        "@cratis/cast": "0.1.0"
+    }
+}