@waypoint-framework/cli 0.2.0

package/dist/util/git.d.ts

@@ -0,0 +1,17 @@
+export interface GitExecOptions {
+    cwd: string;
+    silent?: boolean;
+}
+export declare function git(args: string, opts: GitExecOptions): string;
+export declare function hasRemote(name: string, cwd: string): boolean;
+export declare function getUpstreamUrl(cwd: string): string | undefined;
+export declare function fetchUpstream(cwd: string, refspec?: string): void;
+export declare function getUpstreamTags(cwd: string): string[];
+export declare function commitsBehindUpstream(cwd: string, releaseBranch: string): number;
+export declare function mergeUpstream(cwd: string, releaseBranch: string): {
+    success: boolean;
+    output: string;
+};
+export declare function abortMerge(cwd: string): void;
+export declare function hasUncommittedChanges(cwd: string): boolean;
+export declare function addUpstreamRemote(cwd: string, url: string): void;

package/dist/util/git.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.git = git;
+exports.hasRemote = hasRemote;
+exports.getUpstreamUrl = getUpstreamUrl;
+exports.fetchUpstream = fetchUpstream;
+exports.getUpstreamTags = getUpstreamTags;
+exports.commitsBehindUpstream = commitsBehindUpstream;
+exports.mergeUpstream = mergeUpstream;
+exports.abortMerge = abortMerge;
+exports.hasUncommittedChanges = hasUncommittedChanges;
+exports.addUpstreamRemote = addUpstreamRemote;
+const child_process_1 = require("child_process");
+function git(args, opts) {
+    try {
+        return (0, child_process_1.execSync)(`git ${args}`, {
+            cwd: opts.cwd,
+            encoding: 'utf-8',
+            stdio: opts.silent ? ['pipe', 'pipe', 'pipe'] : undefined,
+        }).trim();
+    }
+    catch (err) {
+        if (opts.silent)
+            return '';
+        throw new Error(`git ${args} failed: ${err.stderr || err.message}`);
+    }
+}
+function hasRemote(name, cwd) {
+    const remotes = git('remote', { cwd, silent: true });
+    return remotes.split('\n').includes(name);
+}
+function getUpstreamUrl(cwd) {
+    if (!hasRemote('upstream', cwd))
+        return undefined;
+    return git('remote get-url upstream', { cwd, silent: true }) || undefined;
+}
+function fetchUpstream(cwd, refspec) {
+    const ref = refspec ? ` ${refspec}` : '';
+    git(`fetch upstream${ref}`, { cwd });
+}
+function getUpstreamTags(cwd) {
+    fetchUpstream(cwd, '--tags');
+    const output = git('tag -l "v*"', { cwd, silent: true });
+    if (!output)
+        return [];
+    return output.split('\n').filter(Boolean);
+}
+function commitsBehindUpstream(cwd, releaseBranch) {
+    const count = git(`rev-list HEAD..upstream/${releaseBranch} --count`, { cwd, silent: true });
+    return parseInt(count, 10) || 0;
+}
+function mergeUpstream(cwd, releaseBranch) {
+    try {
+        const output = git(`merge upstream/${releaseBranch} --no-edit`, { cwd });
+        return { success: true, output };
+    }
+    catch (err) {
+        return { success: false, output: err.message || 'Merge failed' };
+    }
+}
+function abortMerge(cwd) {
+    git('merge --abort', { cwd, silent: true });
+}
+function hasUncommittedChanges(cwd) {
+    const status = git('status --porcelain', { cwd, silent: true });
+    return status.length > 0;
+}
+function addUpstreamRemote(cwd, url) {
+    if (hasRemote('upstream', cwd)) {
+        git(`remote set-url upstream ${url}`, { cwd });
+    }
+    else {
+        git(`remote add upstream ${url}`, { cwd });
+    }
+}
+//# sourceMappingURL=git.js.map

package/dist/util/git.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"git.js","sourceRoot":"","sources":["../../src/util/git.ts"],"names":[],"mappings":";;AAOA,kBAWC;AAED,8BAGC;AAED,wCAGC;AAED,sCAGC;AAED,0CAKC;AAED,sDAMC;AAED,sCAOC;AAED,gCAEC;AAED,sDAGC;AAED,8CAMC;AA1ED,iDAAyC;AAOzC,SAAgB,GAAG,CAAC,IAAY,EAAE,IAAoB;IAClD,IAAI,CAAC;QACD,OAAO,IAAA,wBAAQ,EAAC,OAAO,IAAI,EAAE,EAAE;YAC3B,GAAG,EAAE,IAAI,CAAC,GAAG;YACb,QAAQ,EAAE,OAAO;YACjB,KAAK,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,SAAS;SAC5D,CAAC,CAAC,IAAI,EAAE,CAAC;IACd,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAChB,IAAI,IAAI,CAAC,MAAM;YAAE,OAAO,EAAE,CAAC;QAC3B,MAAM,IAAI,KAAK,CAAC,OAAO,IAAI,YAAY,GAAG,CAAC,MAAM,IAAI,GAAG,CAAC,OAAO,EAAE,CAAC,CAAC;IACxE,CAAC;AACL,CAAC;AAED,SAAgB,SAAS,CAAC,IAAY,EAAE,GAAW;IAC/C,MAAM,OAAO,GAAG,GAAG,CAAC,QAAQ,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACrD,OAAO,OAAO,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC;AAC9C,CAAC;AAED,SAAgB,cAAc,CAAC,GAAW;IACtC,IAAI,CAAC,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC;QAAE,OAAO,SAAS,CAAC;IAClD,OAAO,GAAG,CAAC,yBAAyB,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,IAAI,SAAS,CAAC;AAC9E,CAAC;AAED,SAAgB,aAAa,CAAC,GAAW,EAAE,OAAgB;IACvD,MAAM,GAAG,GAAG,OAAO,CAAC,CAAC,CAAC,IAAI,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IACzC,GAAG,CAAC,iBAAiB,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;AACzC,CAAC;AAED,SAAgB,eAAe,CAAC,GAAW;IACvC,aAAa,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IAC7B,MAAM,MAAM,GAAG,GAAG,CAAC,aAAa,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IACzD,IAAI,CAAC,MAAM;QAAE,OAAO,EAAE,CAAC;IACvB,OAAO,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;AAC9C,CAAC;AAED,SAAgB,qBAAqB,CAAC,GAAW,EAAE,aAAqB;IACpE,MAAM,KAAK,GAAG,GAAG,CACb,2BAA2B,aAAa,UAAU,EAClD,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CACxB,CAAC;IACF,OAAO,QAAQ,CAAC,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,SAAgB,aAAa,CAAC,GAAW,EAAE,aAAqB;IAC5D,IAAI,CAAC;QACD,MAAM,MAAM,GAAG,GAAG,CAAC,kBAAkB,aAAa,YAAY,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;QACzE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;IACrC,CAAC;IAAC,OAAO,GAAQ,EAAE,CAAC;QAChB,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,EAAE,GAAG,CAAC,OAAO,IAAI,cAAc,EAAE,CAAC;IACrE,CAAC;AACL,CAAC;AAED,SAAgB,UAAU,CAAC,GAAW;IAClC,GAAG,CAAC,eAAe,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;AAChD,CAAC;AAED,SAAgB,qBAAqB,CAAC,GAAW;IAC7C,MAAM,MAAM,GAAG,GAAG,CAAC,oBAAoB,EAAE,EAAE,GAAG,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC;IAChE,OAAO,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;AAC7B,CAAC;AAED,SAAgB,iBAAiB,CAAC,GAAW,EAAE,GAAW;IACtD,IAAI,SAAS,CAAC,UAAU,EAAE,GAAG,CAAC,EAAE,CAAC;QAC7B,GAAG,CAAC,2BAA2B,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IACnD,CAAC;SAAM,CAAC;QACJ,GAAG,CAAC,uBAAuB,GAAG,EAAE,EAAE,EAAE,GAAG,EAAE,CAAC,CAAC;IAC/C,CAAC;AACL,CAAC"}

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@waypoint-framework/cli",
+  "version": "0.2.0",
+  "description": "CLI for local validation and workflow versioning in Waypoint Framework projects",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "waypoint": "dist/index.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "ts-node src/index.ts",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@waypoint-framework/core": "^0.1.0",
+    "ajv": "^8.17.1",
+    "commander": "^13.1.0",
+    "js-yaml": "^4.1.0"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "rimraf": "^5.0.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.6.3"
+  }
+}

package/src/commands/init.ts

@@ -0,0 +1,115 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { VersionFile } from '@waypoint-framework/core';
+import {
+    addUpstreamRemote,
+    fetchUpstream,
+    getUpstreamTags,
+    hasRemote,
+    getUpstreamUrl,
+} from '../util/git';
+
+export interface InitOptions {
+    dir: string;
+    workflow: string;
+    version: string;
+    tag?: string;
+}
+
+export async function init(options: InitOptions): Promise<number> {
+    const projectDir = path.resolve(options.dir);
+    const versionPath = path.join(projectDir, '.waypoint', 'version');
+
+    try {
+        await fs.access(versionPath);
+        console.error('.waypoint/version already exists.');
+        console.error('Use "waypoint version" to view current configuration.');
+        return 1;
+    } catch {
+        // expected — file doesn't exist yet
+    }
+
+    if (!options.workflow) {
+        console.error('--workflow is required (e.g. advizo-ai/marketing-workflow)');
+        return 1;
+    }
+
+    const versionLine = options.version || 'v1.x';
+
+    const lineMatch = versionLine.match(/^v?\d+\.x$/);
+    if (!lineMatch) {
+        console.error(`Invalid version line: ${versionLine}. Expected format: v1.x, v2.x, etc.`);
+        return 1;
+    }
+
+    const upstreamUrl = `https://github.com/${options.workflow}.git`;
+
+    console.log(`Configuring upstream remote → ${upstreamUrl}`);
+    addUpstreamRemote(projectDir, upstreamUrl);
+
+    const configuredUrl = getUpstreamUrl(projectDir);
+    if (configuredUrl) {
+        console.log(`  upstream: ${configuredUrl}`);
+    }
+
+    let pinnedTag = options.tag;
+
+    if (!pinnedTag) {
+        console.log('Fetching upstream tags...');
+        try {
+            fetchUpstream(projectDir, '--tags');
+            const tags = getUpstreamTags(projectDir);
+            const latest = VersionFile.findLatestInLine(tags, versionLine);
+            if (latest) {
+                pinnedTag = latest;
+                console.log(`  Latest tag on ${versionLine}: ${pinnedTag}`);
+            } else {
+                const major = versionLine.replace(/\.x$/, '.0.0');
+                pinnedTag = major.startsWith('v') ? major : `v${major}`;
+                console.log(`  No tags found for ${versionLine}, defaulting to ${pinnedTag}`);
+            }
+        } catch {
+            const major = versionLine.replace(/\.x$/, '.0.0');
+            pinnedTag = major.startsWith('v') ? major : `v${major}`;
+            console.log(`  Could not fetch tags, defaulting to ${pinnedTag}`);
+        }
+    }
+
+    try {
+        VersionFile.parseSemVer(pinnedTag);
+    } catch {
+        console.error(`Invalid tag format: ${pinnedTag}. Expected semver like v1.0.0`);
+        return 1;
+    }
+
+    const vf = VersionFile.create(
+        {
+            workflow: options.workflow,
+            version: versionLine,
+            pinned_tag: pinnedTag,
+        },
+        versionPath
+    );
+
+    await vf.save();
+
+    console.log('\nCreated .waypoint/version:');
+    console.log(`  workflow:    ${vf.workflow}`);
+    console.log(`  version:     ${vf.version}`);
+    console.log(`  pinned_tag:  ${vf.pinnedTag}`);
+
+    console.log('\nFetching upstream release branch...');
+    try {
+        fetchUpstream(projectDir, vf.releaseBranch);
+        console.log(`  Fetched upstream/${vf.releaseBranch}`);
+    } catch {
+        console.log(`  Branch upstream/${vf.releaseBranch} not found yet (may need to be created).`);
+    }
+
+    console.log('\nSetup complete. Next steps:');
+    console.log('  1. git add .waypoint/version');
+    console.log('  2. git commit -m "chore: initialize workflow version tracking"');
+    console.log('  3. Run "waypoint version --check-upstream" to verify');
+
+    return 0;
+}

package/src/commands/update.ts

@@ -0,0 +1,155 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { VersionFile } from '@waypoint-framework/core';
+import { validate } from './validate';
+import {
+    hasRemote,
+    fetchUpstream,
+    getUpstreamTags,
+    commitsBehindUpstream,
+    mergeUpstream,
+    abortMerge,
+    hasUncommittedChanges,
+} from '../util/git';
+
+export interface UpdateOptions {
+    dir: string;
+    check: boolean;
+    major: boolean;
+    validate: boolean;
+}
+
+export async function update(options: UpdateOptions): Promise<number> {
+    const projectDir = path.resolve(options.dir);
+    const versionPath = path.join(projectDir, '.waypoint', 'version');
+
+    try {
+        await fs.access(versionPath);
+    } catch {
+        console.error('No .waypoint/version found. Run "waypoint init" first.');
+        return 1;
+    }
+
+    const vf = await VersionFile.fromFile(versionPath);
+
+    if (!hasRemote('upstream', projectDir)) {
+        console.error('No upstream remote configured.');
+        console.error(`Add it with: git remote add upstream https://github.com/${vf.workflow}.git`);
+        return 1;
+    }
+
+    console.log(`Fetching upstream (${vf.workflow})...`);
+    fetchUpstream(projectDir, '--tags');
+    fetchUpstream(projectDir, vf.releaseBranch);
+
+    const tags = getUpstreamTags(projectDir);
+    const latestInLine = VersionFile.findLatestInLine(tags, vf.version);
+    const latestOverall = VersionFile.findLatestTag(tags);
+
+    const hasMinorOrPatch =
+        latestInLine != null &&
+        VersionFile.compareSemVer(latestInLine, vf.pinnedTag) > 0;
+
+    const hasMajor =
+        latestOverall != null &&
+        VersionFile.parseSemVer(latestOverall).major >
+            VersionFile.parseSemVer(vf.pinnedTag).major;
+
+    if (!hasMinorOrPatch && !hasMajor) {
+        console.log(`Already up to date (${vf.pinnedTag}).`);
+        return 0;
+    }
+
+    if (hasMinorOrPatch) {
+        const updateType = VersionFile.classifyUpdate(vf.pinnedTag, latestInLine!);
+        console.log(`Update available (${updateType}): ${vf.pinnedTag} → ${latestInLine}`);
+
+        const behind = commitsBehindUpstream(projectDir, vf.releaseBranch);
+        console.log(`${behind} commit(s) behind upstream/${vf.releaseBranch}`);
+    }
+
+    if (hasMajor && !hasMinorOrPatch) {
+        console.log(`Major version available: ${latestOverall}`);
+        if (!options.major) {
+            console.log('Use --major to upgrade to the next major version.');
+            return 0;
+        }
+    }
+
+    if (hasMajor && options.major) {
+        console.log(`\n⚠ Major update available: ${latestOverall}`);
+        console.log('Major updates may contain breaking schema changes.');
+    }
+
+    if (options.check) {
+        console.log('\n(check-only mode, no changes applied)');
+        return 0;
+    }
+
+    if (hasUncommittedChanges(projectDir)) {
+        console.error('\nUncommitted changes detected. Commit or stash them before updating.');
+        return 1;
+    }
+
+    let targetBranch: string;
+    let targetTag: string;
+
+    if (options.major && hasMajor) {
+        const newMajor = VersionFile.parseSemVer(latestOverall!).major;
+        targetBranch = `release/v${newMajor}.x`;
+        targetTag = latestOverall!;
+
+        console.log(`\nFetching major release branch: ${targetBranch}`);
+        fetchUpstream(projectDir, targetBranch);
+    } else if (hasMinorOrPatch) {
+        targetBranch = vf.releaseBranch;
+        targetTag = latestInLine!;
+    } else {
+        console.log('No applicable updates.');
+        return 0;
+    }
+
+    console.log(`\nMerging upstream/${targetBranch}...`);
+    const result = mergeUpstream(projectDir, targetBranch);
+
+    if (!result.success) {
+        console.error('\nMerge conflicts detected!');
+        console.error('Resolve conflicts manually, then run:');
+        console.error('  git add . && git commit');
+        console.error('  waypoint validate --local --all');
+
+        abortMerge(projectDir);
+        return 1;
+    }
+
+    console.log('Merge successful.');
+
+    const newVersion = options.major && hasMajor
+        ? `v${VersionFile.parseSemVer(targetTag).major}.x`
+        : vf.version;
+
+    const updatedVf = VersionFile.create(
+        {
+            workflow: vf.workflow,
+            version: newVersion,
+            pinned_tag: targetTag,
+        },
+        versionPath
+    );
+    await updatedVf.save();
+    console.log(`Updated .waypoint/version: pinned_tag → ${targetTag}`);
+
+    if (options.validate) {
+        console.log('\nRunning post-update validation...');
+        const exitCode = await validate({ local: true, all: true, dir: projectDir });
+        if (exitCode !== 0) {
+            console.error('\nValidation failed after update.');
+            console.error('Fix validation errors, then commit.');
+            return 1;
+        }
+        console.log('All validations passed.');
+    }
+
+    console.log('\nUpdate complete. Review changes and commit when ready.');
+    return 0;
+}

package/src/commands/validate.ts

@@ -0,0 +1,117 @@
+import * as fs from 'fs/promises';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import Ajv from 'ajv';
+import { WaypointYaml } from '@waypoint-framework/core';
+
+export interface ValidateOptions {
+  local: boolean;
+  all: boolean;
+  dir: string;
+}
+
+export async function validate(options: ValidateOptions): Promise<number> {
+  const projectDir = path.resolve(options.dir);
+  const waypointPath = path.join(projectDir, 'waypoint.yaml');
+
+  try {
+    await fs.access(waypointPath);
+  } catch {
+    console.error(`No waypoint.yaml found in ${projectDir}`);
+    return 1;
+  }
+
+  const wp = await WaypointYaml.fromFile(waypointPath);
+  const schemaMappings = wp.getSchemaMappings(path.join(projectDir, 'schemas'));
+
+  let filesToValidate: string[];
+
+  if (options.all) {
+    filesToValidate = getAllArtifactFiles(wp, projectDir);
+  } else {
+    filesToValidate = getChangedFiles(projectDir);
+  }
+
+  if (filesToValidate.length === 0) {
+    console.log('No files to validate.');
+    return 0;
+  }
+
+  const ajv = new Ajv({ allErrors: true, strict: false });
+  let hasErrors = false;
+
+  for (const filePath of filesToValidate) {
+    const waypointId = wp.findWaypointForFile(filePath);
+    if (!waypointId) {
+      continue;
+    }
+
+    const schemaMapping = schemaMappings.find((m: { waypointId: string }) => m.waypointId === waypointId);
+    if (!schemaMapping) {
+      continue;
+    }
+
+    let schema: any;
+    try {
+      const schemaContent = await fs.readFile(schemaMapping.schemaPath, 'utf-8');
+      schema = JSON.parse(schemaContent);
+    } catch {
+      console.warn(`  Schema not found: ${schemaMapping.schemaPath}`);
+      continue;
+    }
+
+    const fullPath = path.isAbsolute(filePath) ? filePath : path.join(projectDir, filePath);
+    let data: any;
+    try {
+      const content = await fs.readFile(fullPath, 'utf-8');
+      data = JSON.parse(content);
+    } catch {
+      continue;
+    }
+
+    const valid = ajv.validate(schema, data);
+    if (!valid) {
+      hasErrors = true;
+      console.error(`FAIL ${filePath}`);
+      for (const err of ajv.errors || []) {
+        console.error(`  ${err.instancePath || '/'}: ${err.message}`);
+      }
+    } else {
+      console.log(`PASS ${filePath}`);
+    }
+  }
+
+  return hasErrors ? 1 : 0;
+}
+
+function getChangedFiles(projectDir: string): string[] {
+  try {
+    const staged = execSync('git diff --cached --name-only', {
+      cwd: projectDir,
+      encoding: 'utf-8',
+    }).trim();
+
+    if (staged) {
+      return staged.split('\n').filter(Boolean);
+    }
+
+    const unstaged = execSync('git diff --name-only', {
+      cwd: projectDir,
+      encoding: 'utf-8',
+    }).trim();
+
+    return unstaged.split('\n').filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+function getAllArtifactFiles(wp: WaypointYaml, projectDir: string): string[] {
+  const allIds = wp.getAllNodeIds();
+  const files: string[] = [];
+  for (const id of allIds) {
+    files.push(`${id}.json`);
+    files.push(`${id}.md`);
+  }
+  return files;
+}

package/src/commands/version.ts

@@ -0,0 +1,90 @@
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { VersionFile } from '@waypoint-framework/core';
+import {
+    getUpstreamUrl,
+    getUpstreamTags,
+    commitsBehindUpstream,
+    hasRemote,
+} from '../util/git';
+
+export interface VersionOptions {
+    dir: string;
+    checkUpstream: boolean;
+}
+
+export async function version(options: VersionOptions): Promise<number> {
+    const projectDir = path.resolve(options.dir);
+    const versionPath = path.join(projectDir, '.waypoint', 'version');
+
+    try {
+        await fs.access(versionPath);
+    } catch {
+        console.error(`No .waypoint/version found in ${projectDir}`);
+        console.error('Run "waypoint init" to set up workflow version tracking.');
+        return 1;
+    }
+
+    const vf = await VersionFile.fromFile(versionPath);
+
+    console.log('Workflow Version Info');
+    console.log('────────────────────');
+    console.log(`  Workflow:    ${vf.workflow}`);
+    console.log(`  Version:     ${vf.version}`);
+    console.log(`  Pinned Tag:  ${vf.pinnedTag}`);
+    console.log(`  Release Branch: ${vf.releaseBranch}`);
+
+    const upstreamUrl = getUpstreamUrl(projectDir);
+    if (upstreamUrl) {
+        console.log(`  Upstream:    ${upstreamUrl}`);
+    } else {
+        console.log('  Upstream:    (not configured)');
+    }
+
+    if (!options.checkUpstream) return 0;
+
+    if (!hasRemote('upstream', projectDir)) {
+        console.log('\n⚠ No upstream remote configured. Cannot check for updates.');
+        return 0;
+    }
+
+    console.log('\nChecking upstream for updates...');
+
+    try {
+        const tags = getUpstreamTags(projectDir);
+        if (tags.length === 0) {
+            console.log('  No version tags found on upstream.');
+            return 0;
+        }
+
+        const latestInLine = VersionFile.findLatestInLine(tags, vf.version);
+        const latestOverall = VersionFile.findLatestTag(tags);
+
+        if (latestInLine && VersionFile.compareSemVer(latestInLine, vf.pinnedTag) > 0) {
+            const updateType = VersionFile.classifyUpdate(vf.pinnedTag, latestInLine);
+            console.log(`  Update available (${updateType}): ${vf.pinnedTag} → ${latestInLine}`);
+
+            const behind = commitsBehindUpstream(projectDir, vf.releaseBranch);
+            if (behind > 0) {
+                console.log(`  ${behind} commit(s) behind upstream/${vf.releaseBranch}`);
+            }
+            console.log('  Run "waypoint update" to apply.');
+        } else {
+            console.log(`  Up to date on ${vf.version} line (${vf.pinnedTag}).`);
+        }
+
+        if (latestOverall) {
+            const latestSv = VersionFile.parseSemVer(latestOverall);
+            const pinnedSv = VersionFile.parseSemVer(vf.pinnedTag);
+            if (latestSv.major > pinnedSv.major) {
+                console.log(`\n⚠ Major version available: ${latestOverall}`);
+                console.log('  Major updates may contain breaking schema changes.');
+                console.log('  Run "waypoint update --major" to migrate.');
+            }
+        }
+    } catch (err: any) {
+        console.error(`\nFailed to check upstream: ${err.message}`);
+    }
+
+    return 0;
+}

package/src/index.ts

@@ -0,0 +1,80 @@
+#!/usr/bin/env node
+import { Command } from 'commander';
+import { validate } from './commands/validate';
+import { version } from './commands/version';
+import { update } from './commands/update';
+import { init } from './commands/init';
+
+const program = new Command();
+
+program
+  .name('waypoint')
+  .description('Waypoint Framework CLI — local validation and workflow versioning for project repos')
+  .version('0.2.0');
+
+program
+  .command('validate')
+  .description('Validate changed files against their waypoint JSON schemas')
+  .option('--local', 'Run validation locally (default)', true)
+  .option('--all', 'Validate all files, not just changed ones')
+  .option('--dir <path>', 'Project directory (defaults to cwd)', process.cwd())
+  .action(async (options) => {
+    try {
+      const exitCode = await validate(options);
+      process.exit(exitCode);
+    } catch (err: any) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('version')
+  .description('Show workflow version info for this project')
+  .option('--dir <path>', 'Project directory (defaults to cwd)', process.cwd())
+  .option('--check-upstream', 'Check upstream repo for available updates', false)
+  .action(async (options) => {
+    try {
+      const exitCode = await version(options);
+      process.exit(exitCode);
+    } catch (err: any) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('update')
+  .description('Check for and apply workflow updates from the upstream repo')
+  .option('--dir <path>', 'Project directory (defaults to cwd)', process.cwd())
+  .option('--check', 'Only check for updates, do not apply', false)
+  .option('--major', 'Allow major version upgrades (breaking changes)', false)
+  .option('--no-validate', 'Skip post-update validation')
+  .action(async (options) => {
+    try {
+      const exitCode = await update(options);
+      process.exit(exitCode);
+    } catch (err: any) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program
+  .command('init')
+  .description('Initialize workflow version tracking for a project fork')
+  .requiredOption('--workflow <owner/repo>', 'Upstream workflow repo (e.g. advizo-ai/marketing-workflow)')
+  .option('--version <line>', 'Version line to track (e.g. v1.x)', 'v1.x')
+  .option('--tag <tag>', 'Specific tag to pin (auto-detected if omitted)')
+  .option('--dir <path>', 'Project directory (defaults to cwd)', process.cwd())
+  .action(async (options) => {
+    try {
+      const exitCode = await init(options);
+      process.exit(exitCode);
+    } catch (err: any) {
+      console.error(`Error: ${err.message}`);
+      process.exit(1);
+    }
+  });
+
+program.parse();