@learncard/cli 3.6.7 → 4.0.0

package/package.json

@@ -1,9 +1,21 @@
 {
     "name": "@learncard/cli",
-    "version": "3.6.7",
+    "version": "4.0.0",
     "description": "Command Line Interface for LearnCard",
     "main": "dist/index.js",
-    "bin": "dist/index.js",
+    "bin": {
+        "learncard": "dist/index.js",
+        "cli": "dist/index.js"
+    },
+    "files": [
+        "dist",
+        "examples",
+        "README.md",
+        "CHANGELOG.md"
+    ],
+    "engines": {
+        "node": ">=20"
+    },
     "scripts": {
         "start": "bun scripts/embed-snippets.ts && bun --conditions=development src/index.tsx",
         "start:built": "bun run build && node --enable-source-maps dist/index.js",
@@ -16,18 +28,18 @@
     "author": "Learning Economy Foundation (www.learningeconomy.io)",
     "license": "MIT",
     "dependencies": {
-        "@learncard/core": "9.4.41",
-        "@learncard/didkit-plugin": "^1.10.6",
-        "@learncard/holder-continuity": "0.2.25",
-        "@learncard/init": "^2.5.6",
-        "@learncard/lca-api-plugin": "2.0.12",
-        "@learncard/learn-cloud-plugin": "2.3.48",
-        "@learncard/ler-rs-plugin": "0.1.32",
-        "@learncard/linked-claims-plugin": "0.2.41",
-        "@learncard/network-brain-client": "2.6.0",
-        "@learncard/open-badge-v2-plugin": "1.1.42",
-        "@learncard/render-method-plugin": "12.0.0",
-        "@learncard/types": "5.24.0",
+        "@learncard/core": "9.4.42",
+        "@learncard/didkit-plugin": "^1.10.8",
+        "@learncard/holder-continuity": "0.2.27",
+        "@learncard/init": "^2.5.8",
+        "@learncard/lca-api-plugin": "2.0.14",
+        "@learncard/learn-cloud-plugin": "2.3.50",
+        "@learncard/ler-rs-plugin": "0.1.33",
+        "@learncard/linked-claims-plugin": "0.2.42",
+        "@learncard/network-brain-client": "2.6.2",
+        "@learncard/open-badge-v2-plugin": "1.1.43",
+        "@learncard/render-method-plugin": "12.0.1",
+        "@learncard/types": "5.24.1",
         "clipboardy": "^4.0.0",
         "commander": "^9.3.0",
         "figlet": "^1.5.2",
@@ -37,7 +49,7 @@
         "zod": "^4.1.13"
     },
     "devDependencies": {
-        "@learncard/credential-library": "2.1.4",
+        "@learncard/credential-library": "2.1.5",
         "@rollup/plugin-json": "^4.1.0",
         "@types/cors": "^2.8.12",
         "@types/figlet": "^1.5.4",

package/project.json

@@ -1,42 +0,0 @@
-{
-    "$schema": "../../node_modules/nx/schemas/project-schema.json",
-    "name": "cli",
-    "sourceRoot": "packages/learn-card-cli/src",
-    "projectType": "library",
-    "root": "packages/learn-card-cli",
-    "tags": [],
-    "implicitDependencies": [
-        "nx-run-command",
-        "types",
-        "init",
-        "open-badge-v2-plugin",
-        "holder-continuity"
-    ],
-    "namedInputs": {
-        "source": ["{projectRoot}/src/**/*"],
-        "dist": ["{projectRoot}/dist/**/*"]
-    },
-    "targets": {
-        "build": {
-            "executor": "nx:run-script",
-            "inputs": ["source"],
-            "options": {
-                "script": "build"
-            }
-        },
-        "test": {
-            "executor": "nx:run-script",
-            "inputs": ["source"],
-            "options": {
-                "script": "test"
-            }
-        },
-        "start": {
-            "executor": "nx:run-script",
-            "dependsOn": ["^build"],
-            "options": {
-                "script": "start"
-            }
-        }
-    }
-}

package/rollup.config.js

@@ -1,34 +0,0 @@
-import json from '@rollup/plugin-json';
-import esbuild from 'rollup-plugin-esbuild';
-
-import { readFileSync } from 'node:fs';
-
-const packageJson = JSON.parse(readFileSync(new URL('./package.json', import.meta.url), 'utf8'));
-
-export default [
-    {
-        input: ['src/index.tsx'],
-        output: [
-            {
-                file: packageJson.bin,
-                format: 'cjs',
-                banner: '#!/usr/bin/env node',
-                inlineDynamicImports: true,
-            },
-        ],
-        plugins: [
-            json(),
-            esbuild(),
-            {
-                name: 'native-webhook-import',
-                renderDynamicImport({ moduleId }) {
-                    // Rollup 2 otherwise emits require(data:...), which Node cannot load.
-                    if (moduleId.endsWith('/src/webhook.ts')) {
-                        return { left: 'import(', right: ')' };
-                    }
-                    return null;
-                },
-            },
-        ],
-    },
-];

package/scripts/embed-snippets.ts

@@ -1,47 +0,0 @@
-import { randomUUID } from 'node:crypto';
-import { mkdir, readFile, rename, rm, writeFile } from 'node:fs/promises';
-import { dirname, resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-
-const root = resolve(dirname(fileURLToPath(import.meta.url)), '../../..');
-const snippets = {
-    SEND_MJS: 'quickstart/send.mjs',
-    SEND_SH: 'quickstart/send.sh',
-    SEND_FROM_TEMPLATE_MJS: 'quickstart/send-from-template.mjs',
-    WEBHOOK_MJS: 'cli/webhook.mjs',
-    CLAIM_BUTTON_HTML: 'cli/claim-button.html',
-    CREATE_CONTRACT_MJS: 'consentflow/create-contract.mjs',
-    CONSENT_CALLBACK_MJS: 'consentflow/consent-callback.mjs',
-    READ_USER_DATA_MJS: 'consentflow/read-user-data.mjs',
-    ISSUE_THROUGH_CONTRACT_MJS: 'consentflow/issue-through-contract.mjs',
-};
-/** Deterministic and atomic: independent checkout users never read a partial module. */
-export const embedSnippets = async (signal?: AbortSignal): Promise<void> => {
-    signal?.throwIfAborted();
-    const lines = await Promise.all(
-        Object.entries(snippets).map(
-            async ([name, file]) =>
-                `export const ${name} = ${JSON.stringify(await readFile(resolve(root, 'docs/snippets', file), { encoding: 'utf8', signal }))};\n`
-        )
-    );
-    const output = resolve(root, 'packages/learn-card-cli/src/generated/snippets.ts');
-    const content = '// Generated from docs/snippets. Do not edit.\n' + lines.join('');
-    try {
-        if ((await readFile(output, 'utf8')) === content) return;
-    } catch (error) {
-        if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
-    }
-    await mkdir(dirname(output), { recursive: true });
-    const temporary = `${output}.${randomUUID()}.tmp`;
-    try {
-        await writeFile(temporary, content, { flag: 'wx', signal });
-        signal?.throwIfAborted();
-        await rename(temporary, output);
-    } finally {
-        await rm(temporary, { force: true });
-    }
-};
-
-if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
-    await embedSnippets();
-}

package/src/auth-grant.test.ts

@@ -1,54 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import {
-    describeActAs,
-    getGrantActAs,
-    normalizeActAs,
-    type AuthGrantWithActAs,
-} from './auth-grant';
-
-describe('getGrantActAs', () => {
-    it('reads actAs off a grant', () => {
-        const grant: AuthGrantWithActAs = { id: 'g1', actAs: 'sc-greenville,sc-north' };
-        expect(getGrantActAs(grant)).toBe('sc-greenville,sc-north');
-    });
-
-    it('is undefined when the grant has no actAs', () => {
-        expect(getGrantActAs({ id: 'g1' })).toBeUndefined();
-    });
-
-    it.each([null, ''])(
-        'coerces %j from the wire to undefined so it matches an absent spec value',
-        value => {
-            expect(getGrantActAs({ id: 'g1', actAs: value as unknown as string })).toBeUndefined();
-        }
-    );
-});
-
-describe('describeActAs', () => {
-    it('renders a comma-separated list with spaces', () => {
-        expect(describeActAs('sc-greenville,sc-north')).toBe('sc-greenville, sc-north');
-    });
-
-    it('renders "*" as any managed profile', () => {
-        expect(describeActAs('*')).toBe('any managed profile');
-    });
-
-    it('renders undefined as no delegation', () => {
-        expect(describeActAs(undefined)).toBe('no delegation');
-    });
-});
-
-describe('normalizeActAs', () => {
-    it('sorts, trims, and de-duplicates profile IDs', () => {
-        expect(normalizeActAs(' sc-north , sc-greenville,sc-north ')).toBe(
-            'sc-greenville,sc-north'
-        );
-    });
-
-    it('keeps "*" and treats empty values as no delegation', () => {
-        expect(normalizeActAs(' * ')).toBe('*');
-        expect(normalizeActAs('')).toBeUndefined();
-        expect(normalizeActAs(' , ')).toBeUndefined();
-        expect(normalizeActAs(undefined)).toBeUndefined();
-    });
-});

package/src/auth-grant.ts

@@ -1,34 +0,0 @@
-import type { AuthGrantType } from '@learncard/types';
-
-/**
- * `actAs` on an auth grant: `'*'` = the token may act as any managed profile,
- * a comma-separated list of profileIds = only those profiles, absent = the
- * token may not act as anyone (deny-by-default).
- */
-export type AuthGrantWithActAs = Partial<AuthGrantType>;
-
-/** Coerces `null` / `''` from the wire to `undefined` so drift checks compare like with like. */
-export const getGrantActAs = (grant: Partial<AuthGrantType>): string | undefined =>
-    grant.actAs || undefined;
-
-/** `'*'` -> "any managed profile"; `'a,b'` -> "a, b"; absent -> "no delegation". */
-export const describeActAs = (actAs: string | undefined): string => {
-    if (!actAs) return 'no delegation';
-    if (actAs === '*') return 'any managed profile';
-    return actAs.split(',').filter(Boolean).join(', ');
-};
-
-/** Order- and whitespace-insensitive form for drift checks: `'b, a'` and `'a,b'` are the same policy. */
-export const normalizeActAs = (actAs: string | undefined): string | undefined => {
-    if (!actAs) return undefined;
-    if (actAs.trim() === '*') return '*';
-    const ids = [
-        ...new Set(
-            actAs
-                .split(',')
-                .map(id => id.trim())
-                .filter(Boolean)
-        ),
-    ].sort();
-    return ids.length ? ids.join(',') : undefined;
-};

package/src/clr/validate.test.ts

@@ -1,65 +0,0 @@
-import { describe, expect, it } from 'vitest';
-import { clrProvisionalTranscript, clrWestbridgeFull } from '@learncard/credential-library';
-
-import { validateClr } from './validate';
-
-const clone = <T>(value: T): T => structuredClone(value);
-
-const provisional = (): Record<string, unknown> =>
-    clone(clrProvisionalTranscript.credential) as Record<string, unknown>;
-
-describe('validateClr', () => {
-    it('passes the library provisional transcript with zero errors', () => {
-        const result = validateClr(provisional(), { profile: 'provisional' });
-        expect(result.errors).toEqual([]);
-        expect(result.warnings).toEqual([]);
-    });
-
-    it('errors on partial when the same transcript is checked as official', () => {
-        const result = validateClr(provisional(), { profile: 'official' });
-        expect(result.errors.some(e => /partial/i.test(e))).toBe(true);
-    });
-
-    it('errors when @context uses the 2.0.1 URL that requires remote loading', () => {
-        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
-        credential['@context'] = (credential['@context'] as unknown[]).map(entry =>
-            entry === 'https://purl.imsglobal.org/spec/clr/v2p0/context.json'
-                ? 'https://purl.imsglobal.org/spec/clr/v2p0/context-2.0.1.json'
-                : entry
-        );
-        const result = validateClr(credential);
-        expect(
-            result.errors.some(e => e.includes('2.0.1 URL requires remote context loading'))
-        ).toBe(true);
-    });
-
-    it('errors when id is missing', () => {
-        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
-        delete credential.id;
-        const result = validateClr(credential);
-        expect(result.errors.some(e => /^id:/.test(e))).toBe(true);
-    });
-
-    it('warns on a dateOfBirth field added anywhere in the document', () => {
-        const credential = clone(clrWestbridgeFull.credential) as Record<string, unknown>;
-        (credential.credentialSubject as Record<string, unknown>).dateOfBirth = '1999-03-14';
-        const result = validateClr(credential, { profile: 'official' });
-        expect(result.warnings.some(e => /dateOfBirth/.test(e))).toBe(true);
-    });
-
-    it('warns when a provisional transcript omits validUntil', () => {
-        const credential = provisional();
-        delete credential.validUntil;
-        const result = validateClr(credential, { profile: 'provisional' });
-        expect(result.warnings.some(e => /validUntil/.test(e))).toBe(true);
-    });
-
-    it('errors when an InProgress result has no Status-typed ResultDescription', () => {
-        const credential = provisional();
-        const subject = credential.credentialSubject as Record<string, unknown>;
-        const achievement = (subject.achievement as Record<string, unknown>[])[0]!;
-        (achievement.resultDescription as Record<string, unknown>[])[0]!.resultType = 'RawScore';
-        const result = validateClr(credential, { profile: 'provisional' });
-        expect(result.errors.some(e => /resultType "Status"/.test(e))).toBe(true);
-    });
-});

package/src/clr/validate.ts

@@ -1,242 +0,0 @@
-import { ClrCredentialValidator, UnsignedClrCredentialValidator } from '@learncard/types';
-
-/**
- * Issuer-facing lint profile. `provisional` transcripts are expected to change again
- * before finalization; `official` transcripts are the final, certified record.
- */
-export type ClrValidationProfile = 'provisional' | 'official';
-
-export interface ClrValidationOptions {
-    profile?: ClrValidationProfile;
-}
-
-export interface ClrValidationSummary {
-    name?: string;
-    id?: string;
-    partial?: boolean;
-    achievementCount: number;
-    resultStatuses: Record<string, number>;
-}
-
-export interface ClrValidationResult {
-    errors: string[];
-    warnings: string[];
-    summary: ClrValidationSummary;
-}
-
-const CLR_V2_CONTEXT_URL = 'https://purl.imsglobal.org/spec/clr/v2p0/context.json';
-const CLR_V2_CONTEXT_PATTERN = /purl\.imsglobal\.org\/spec\/clr\/v2p0\/context/;
-const CLR_V2_LEGACY_CONTEXT_PATTERN = /context-2\.0\.1\.json/;
-const PII_KEY_PATTERN = /ssn|socialsecurity|dateofbirth|dob|birthdate/i;
-const IN_PROGRESS_STATUSES = new Set(['InProgress', 'Provisional']);
-
-const isRecord = (value: unknown): value is Record<string, unknown> =>
-    typeof value === 'object' && value !== null && !Array.isArray(value);
-
-const toArray = (value: unknown): unknown[] => {
-    if (value === undefined || value === null) return [];
-    return Array.isArray(value) ? value : [value];
-};
-
-/** `@context` must include the CLR v2 context; the 2.0.1 URL fails to sign (remote-load only). */
-const lintContext = (doc: Record<string, unknown>, errors: string[]): void => {
-    const contexts = toArray(doc['@context']).filter(
-        (entry): entry is string => typeof entry === 'string'
-    );
-    const clrEntry = contexts.find(entry => CLR_V2_CONTEXT_PATTERN.test(entry));
-    if (!clrEntry) {
-        errors.push(`@context: must include the CLR v2 context (${CLR_V2_CONTEXT_URL}).`);
-        return;
-    }
-    if (CLR_V2_LEGACY_CONTEXT_PATTERN.test(clrEntry)) {
-        errors.push(
-            `Use ${CLR_V2_CONTEXT_URL} (the 2.0.1 URL requires remote context loading and will fail to sign)`
-        );
-    }
-};
-
-/** A missing id is an error; a non-`urn:uuid:` id is a warning (ids must be stable across versions). */
-const lintId = (doc: Record<string, unknown>, errors: string[], warnings: string[]): void => {
-    const id = doc.id;
-    if (typeof id !== 'string' || !id) {
-        errors.push('id: missing — every CLR transcript needs a stable id.');
-        return;
-    }
-    if (!id.startsWith('urn:uuid:')) {
-        warnings.push('id: use a stable urn:uuid per transcript, never per version');
-    }
-};
-
-/** Recursively flag keys that look like they hold PII, wherever they appear in the document. */
-const collectPii = (value: unknown, path: string, warnings: string[]): void => {
-    if (Array.isArray(value)) {
-        value.forEach((item, index) => collectPii(item, `${path}[${index}]`, warnings));
-        return;
-    }
-    if (!isRecord(value)) return;
-    for (const [key, nested] of Object.entries(value)) {
-        const nextPath = path ? `${path}.${key}` : key;
-        if (PII_KEY_PATTERN.test(key)) {
-            warnings.push(
-                `${nextPath}: possible PII field ("${key}") — avoid embedding sensitive personal data in a transcript.`
-            );
-        }
-        collectPii(nested, nextPath, warnings);
-    }
-};
-
-interface ClrResultNode {
-    path: string;
-    status?: string;
-    resultDescription?: string;
-}
-
-interface ClrWalkData {
-    achievementCount: number;
-    resultDescriptionTypes: Map<string, string>;
-    results: ClrResultNode[];
-}
-
-const addAchievement = (achievement: unknown, data: ClrWalkData): void => {
-    if (!isRecord(achievement)) return;
-    data.achievementCount += 1;
-    for (const resultDescription of toArray(achievement.resultDescription)) {
-        if (
-            isRecord(resultDescription) &&
-            typeof resultDescription.id === 'string' &&
-            typeof resultDescription.resultType === 'string'
-        ) {
-            data.resultDescriptionTypes.set(resultDescription.id, resultDescription.resultType);
-        }
-    }
-};
-
-/**
- * Walks the CLR document collecting every achievement (top-level and nested, so
- * `resultDescription`s from both can satisfy a result's reference), and every result
- * carried by a nested `AchievementCredential` (CLR subjects have no `result` field of
- * their own — only nested verifiableCredentials do).
- */
-const walkClr = (doc: Record<string, unknown>): ClrWalkData => {
-    const data: ClrWalkData = {
-        achievementCount: 0,
-        resultDescriptionTypes: new Map(),
-        results: [],
-    };
-
-    toArray(doc.credentialSubject).forEach((subject, subjectIndex) => {
-        if (!isRecord(subject)) return;
-
-        for (const achievement of toArray(subject.achievement)) addAchievement(achievement, data);
-
-        toArray(subject.verifiableCredential).forEach((nested, nestedIndex) => {
-            if (!isRecord(nested)) return;
-
-            toArray(nested.credentialSubject).forEach((nestedSubject, nestedSubjectIndex) => {
-                if (!isRecord(nestedSubject)) return;
-
-                for (const achievement of toArray(nestedSubject.achievement)) {
-                    addAchievement(achievement, data);
-                }
-
-                for (const result of toArray(nestedSubject.result)) {
-                    if (!isRecord(result)) continue;
-                    data.results.push({
-                        path: `credentialSubject[${subjectIndex}].verifiableCredential[${nestedIndex}].credentialSubject[${nestedSubjectIndex}].result`,
-                        status: typeof result.status === 'string' ? result.status : undefined,
-                        resultDescription:
-                            typeof result.resultDescription === 'string'
-                                ? result.resultDescription
-                                : undefined,
-                    });
-                }
-            });
-        });
-    });
-
-    return data;
-};
-
-/**
- * Lints a CLR 2.0 transcript (signed or unsigned) against schema and issuer-profile rules.
- * Pure: performs no I/O and never throws on malformed input — problems are reported in
- * `errors`/`warnings` instead.
- */
-export const validateClr = (
-    json: unknown,
-    opts: ClrValidationOptions = {}
-): ClrValidationResult => {
-    const errors: string[] = [];
-    const warnings: string[] = [];
-
-    const hasProof = isRecord(json) && json.proof !== undefined;
-    const parsed = hasProof
-        ? ClrCredentialValidator.safeParse(json)
-        : UnsignedClrCredentialValidator.safeParse(json);
-
-    if (!parsed.success) {
-        for (const issue of parsed.error.issues) {
-            const path = issue.path.length ? issue.path.join('.') : '(root)';
-            errors.push(`${path}: ${issue.message}`);
-        }
-    }
-
-    const doc = isRecord(json) ? json : {};
-
-    lintContext(doc, errors);
-    lintId(doc, errors, warnings);
-    collectPii(doc, '', warnings);
-
-    const walked = walkClr(doc);
-
-    const resultStatuses: Record<string, number> = {};
-    for (const result of walked.results) {
-        if (!result.status) continue;
-        resultStatuses[result.status] = (resultStatuses[result.status] ?? 0) + 1;
-    }
-
-    const partial = typeof doc.partial === 'boolean' ? doc.partial : undefined;
-
-    if (opts.profile === 'provisional') {
-        if (partial !== true) {
-            errors.push('partial: must be true for a provisional transcript (set partial: true).');
-        }
-        for (const result of walked.results) {
-            if (!result.status || !IN_PROGRESS_STATUSES.has(result.status)) continue;
-            const resultType = result.resultDescription
-                ? walked.resultDescriptionTypes.get(result.resultDescription)
-                : undefined;
-            if (resultType !== 'Status') {
-                errors.push(
-                    `${result.path}: status "${result.status}" must reference a ResultDescription with resultType "Status" (found ${resultType ? `"${resultType}"` : 'none'}).`
-                );
-            }
-        }
-        if (typeof doc.validUntil !== 'string' || !doc.validUntil) {
-            warnings.push(
-                'validUntil: missing — provisional transcripts should set an expected finalization date.'
-            );
-        }
-    } else if (opts.profile === 'official') {
-        if (partial === true) {
-            errors.push('partial: must not be true for an official transcript.');
-        }
-        for (const result of walked.results) {
-            if (result.status && IN_PROGRESS_STATUSES.has(result.status)) {
-                errors.push(
-                    `${result.path}: status "${result.status}" is not allowed in an official transcript.`
-                );
-            }
-        }
-    }
-
-    const summary: ClrValidationSummary = {
-        name: typeof doc.name === 'string' ? doc.name : undefined,
-        id: typeof doc.id === 'string' ? doc.id : undefined,
-        partial,
-        achievementCount: walked.achievementCount,
-        resultStatuses,
-    };
-
-    return { errors, warnings, summary };
-};