ember-tribe 2.5.3 → 2.6.1

package/bin/storylang

@@ -0,0 +1,61 @@
+#!/usr/bin/env node
+'use strict';
+
+const path = require('path');
+const args = process.argv.slice(2);
+const command = args[0];
+const flags = args.slice(1);
+
+const pull = require('../lib/storylang/pull');
+const push = require('../lib/storylang/push');
+
+const CWD = process.cwd();
+
+function printUsage() {
+  console.log(`
+storylang — ember-tribe spec synchroniser
+
+Usage:
+  storylang <command> [options]
+
+Commands:
+  pull          Updates config/storylang.json from current project files
+  push          Generates any missing routes, components, services, helpers, modifiers, and controllers
+  push -o       Regenerates all artefacts in storylang.json, overwriting existing files
+
+Examples:
+  storylang pull
+  storylang push
+  storylang push -o
+`);
+}
+
+async function main() {
+  switch (command) {
+    case 'pull':
+      await pull(CWD);
+      break;
+
+    case 'push': {
+      const overwrite = flags.includes('-o');
+      await push(CWD, { overwrite });
+      break;
+    }
+
+    case undefined:
+    case '--help':
+    case '-h':
+      printUsage();
+      break;
+
+    default:
+      console.error(`Unknown command: "${command}"`);
+      printUsage();
+      process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('storylang error:', err.message);
+  process.exit(1);
+});

package/blueprints/ember-tribe/index.js

@@ -17,19 +17,20 @@ module.exports = {
         { name: 'ember-math-helpers' },
         { name: 'ember-cli-string-helpers' },
         { name: 'ember-promise-helpers' },
-        { name: '@ember/test-waiters' },
+        { name: '@ember/test-waiters', target: '^3.1.0' },
         { name: 'ember-tag-input' },
         { name: 'ember-file-upload' },
         { name: 'ember-toggle' },
-        { name: 'ember-concurrency' },
+        { name: 'ember-basic-dropdown' },
+        { name: 'ember-power-select' },
         { name: 'ember-click-outside' },
         { name: 'ember-web-app' },
         { name: 'tracked-built-ins' },
         { name: 'ember-keyboard' },
         { name: 'ember-router-scroll' },
+        { name: 'ember-concurrency' },
         { name: 'ember-table' },
         { name: 'ember-animated' },
-        { name: 'ember-power-select' },
       ],
     }).then(() => {
       return this.addPackagesToProject([

package/lib/storylang/pull.js

@@ -0,0 +1,357 @@
+'use strict';
+
+/**
+ * storylang pull
+ *
+ * Scans the current Ember project and writes/updates config/storylang.json
+ * from the actual files that exist in the app/ directory.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function toCamelCase(str) {
+  return str.replace(/-([a-z])/g, (_, c) => c.toUpperCase());
+}
+
+/**
+ * Walk a directory and return all files (recursively) that pass the filter fn.
+ */
+function walkDir(dir, filterFn = () => true) {
+  if (!fs.existsSync(dir)) return [];
+  const results = [];
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const fullPath = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      results.push(...walkDir(fullPath, filterFn));
+    } else if (filterFn(entry.name, fullPath)) {
+      results.push(fullPath);
+    }
+  }
+  return results;
+}
+
+/**
+ * Given a file path inside app/<category>/, derive a kebab-case name
+ * suitable for storylang.json.
+ */
+function nameFromPath(filePath, appDir, category) {
+  const rel = path.relative(path.join(appDir, category), filePath);
+  // strip extension(s) and turn path separators into slashes (nested components)
+  return rel
+    .replace(/\.(js|ts|hbs|scss|css)$/, '')
+    .split(path.sep)
+    .join('/');
+}
+
+// ---------------------------------------------------------------------------
+// Parsers — extract metadata from source files
+// ---------------------------------------------------------------------------
+
+/**
+ * Very lightweight static analysis: look for @tracked, @action, @service,
+ * imported helpers / modifiers, and inherited args from HBS counterpart.
+ */
+function parseJsFile(filePath) {
+  const src = fs.existsSync(filePath) ? fs.readFileSync(filePath, 'utf8') : '';
+
+  // @tracked varName
+  const trackedVars = [...src.matchAll(/@tracked\s+(\w+)\s*(?:=\s*([^;]+))?/g)].map(
+    ([, name, val]) => {
+      const type = inferType(val);
+      return { [name]: type };
+    }
+  );
+
+  // @action methodName(
+  const actions = [...src.matchAll(/@action\s*\n?\s*(?:async\s+)?(\w+)\s*\(/g)].map(
+    ([, name]) => name
+  );
+
+  // @service serviceName;
+  const services = [...src.matchAll(/@service\s+(\w+)/g)].map(([, name]) => name);
+
+  // queryParams = { key: ... }
+  const getVars = [...src.matchAll(/queryParams\s*=\s*\{([^}]+)\}/gs)].flatMap(([, block]) =>
+    [...block.matchAll(/(\w+)\s*:/g)].map(([, k]) => ({ [k]: 'string' }))
+  );
+
+  return { trackedVars, actions, services, getVars };
+}
+
+function inferType(val = '') {
+  val = (val || '').trim();
+  if (val === 'false' || val === 'true') return 'bool';
+  if (val.startsWith('[')) return 'array';
+  if (val.startsWith('{') || val.startsWith('new Map') || val.startsWith('new Set'))
+    return 'object';
+  if (/^\d+$/.test(val)) return 'int';
+  if (val.startsWith("'") || val.startsWith('"') || val.startsWith('`')) return 'string';
+  return 'string';
+}
+
+/**
+ * Parse a Handlebars template for:
+ *  - @arg references  → inherited_args
+ *  - <ComponentName> invocations → sub-components used
+ *  - {{helper-name}} calls → helpers used
+ *  - {{modifier}} element modifiers → modifiers used
+ */
+function parseHbsFile(filePath) {
+  if (!fs.existsSync(filePath)) return { inheritedArgs: [], helpers: [], modifiers: [], components: [] };
+
+  const src = fs.readFileSync(filePath, 'utf8');
+
+  // @argName (distinct, excluding @glimmer internals)
+  const inheritedArgsSet = new Set(
+    [...src.matchAll(/@(\w[\w.]*)/g)]
+      .map(([, name]) => name.split('.')[0])
+      .filter((n) => !['ember', 'glimmer'].includes(n))
+  );
+  const inheritedArgs = [...inheritedArgsSet].map((name) => ({ [name]: 'var' }));
+
+  // {{some-helper ...}} — exclude built-ins
+  const builtinHelpers = new Set([
+    'if', 'unless', 'each', 'let', 'with', 'yield', 'outlet', 'component',
+    'on', 'get', 'concat', 'array', 'hash', 'log', 'action', 'mut',
+    'page-title', 'link-to', 'BasicDropdownWormhole',
+  ]);
+  const helpersSet = new Set(
+    [...src.matchAll(/\{\{([\w-]+)/g)]
+      .map(([, name]) => name)
+      .filter((n) => n.includes('-') && !builtinHelpers.has(n))
+  );
+  const helpers = [...helpersSet];
+
+  // {{modifier-name}} inside element modifier position — {{some-modifier ...}}
+  const modifiersSet = new Set(
+    [...src.matchAll(/\{\{([\w-]+-modifier|autofocus|tooltip|play-when|[\w-]+)\s/g)]
+      .map(([, name]) => name)
+      .filter((n) => helpers.includes(n) === false && !builtinHelpers.has(n))
+  );
+  const modifiers = [...modifiersSet];
+
+  // <ComponentName  (PascalCase or path-style)
+  const componentsSet = new Set(
+    [...src.matchAll(/<([A-Z][\w::/]*)/g)].map(([, name]) => name)
+  );
+  const components = [...componentsSet];
+
+  return { inheritedArgs, helpers, modifiers, components };
+}
+
+/**
+ * Sniff the type of component from its name, matching README built-in types.
+ */
+function guessComponentType(name) {
+  const LAYOUT = ['table', 'figure', 'accordion', 'card', 'list-group', 'navbar', 'nav', 'tab', 'breadcrumb'];
+  const INTERACTIVE = [
+    'button', 'button-group', 'dropdown', 'modal', 'collapse', 'offcanvas', 'pagination',
+    'popover', 'tooltip', 'swiper-carousel', 'videojs-player', 'howlerjs-player', 'input-field',
+    'input-group', 'textarea', 'checkbox', 'radio', 'range', 'select', 'multi-select', 'date',
+    'file-uploader', 'alert', 'badge', 'toast', 'placeholder', 'progress', 'spinner', 'scrollspy',
+  ];
+  for (const t of [...LAYOUT, ...INTERACTIVE]) {
+    if (name.includes(t)) return t;
+  }
+  return 'component';
+}
+
+// ---------------------------------------------------------------------------
+// Section builders
+// ---------------------------------------------------------------------------
+
+function buildComponents(appDir) {
+  const componentDir = path.join(appDir, 'components');
+  const jsFiles = walkDir(componentDir, (n) => /\.(js|ts)$/.test(n));
+
+  return jsFiles.map((jsFile) => {
+    const name = nameFromPath(jsFile, appDir, 'components');
+    const hbsFile = jsFile.replace(/\.(js|ts)$/, '.hbs');
+    const { trackedVars, actions, services } = parseJsFile(jsFile);
+    const { inheritedArgs, helpers, modifiers } = parseHbsFile(hbsFile);
+
+    return {
+      name,
+      type: guessComponentType(name),
+      tracked_vars: trackedVars,
+      inherited_args: inheritedArgs,
+      actions,
+      helpers,
+      modifiers,
+      services,
+    };
+  });
+}
+
+function buildRoutes(appDir) {
+  const routeDir = path.join(appDir, 'routes');
+  const jsFiles = walkDir(routeDir, (n) => /\.(js|ts)$/.test(n));
+
+  return jsFiles.map((jsFile) => {
+    const name = nameFromPath(jsFile, appDir, 'routes');
+    const hbsFile = path.join(appDir, 'templates', name.replace(/\/$/, '') + '.hbs');
+    const { trackedVars, actions, services, getVars } = parseJsFile(jsFile);
+    const { helpers, components } = parseHbsFile(hbsFile);
+
+    return {
+      name,
+      tracked_vars: trackedVars,
+      get_vars: getVars,
+      actions,
+      helpers,
+      services,
+      components,
+      types: [],
+    };
+  });
+}
+
+function buildServices(appDir) {
+  const serviceDir = path.join(appDir, 'services');
+  const jsFiles = walkDir(serviceDir, (n) => /\.(js|ts)$/.test(n));
+
+  return jsFiles.map((jsFile) => {
+    const name = nameFromPath(jsFile, appDir, 'services');
+    const { trackedVars, actions, services } = parseJsFile(jsFile);
+    return { name, tracked_vars: trackedVars, actions, services };
+  });
+}
+
+function buildHelpers(appDir) {
+  const helperDir = path.join(appDir, 'helpers');
+  const jsFiles = walkDir(helperDir, (n) => /\.(js|ts)$/.test(n));
+
+  return jsFiles.map((jsFile) => {
+    const name = nameFromPath(jsFile, appDir, 'helpers');
+    const src = fs.readFileSync(jsFile, 'utf8');
+
+    // Infer args from function signature
+    const sig = src.match(/function\s+\w*\s*\(\[([^\]]*)\](?:,\s*\{([^}]*)\})?\)/);
+    const posArgs = sig ? sig[1].split(',').map((s) => s.trim()).filter(Boolean).map((a) => ({ [a]: 'string' })) : [];
+    const namedArgs = sig && sig[2]
+      ? sig[2].split(',').map((s) => s.trim().split(/\s*=\s*/)[0]).filter(Boolean).map((a) => ({ [a]: 'string' }))
+      : [];
+
+    return {
+      name,
+      description: '',
+      args: [...posArgs, ...namedArgs],
+      return: 'string',
+    };
+  });
+}
+
+function buildModifiers(appDir) {
+  const modifierDir = path.join(appDir, 'modifiers');
+  const jsFiles = walkDir(modifierDir, (n) => /\.(js|ts)$/.test(n));
+
+  return jsFiles.map((jsFile) => {
+    const name = nameFromPath(jsFile, appDir, 'modifiers');
+    const { services } = parseJsFile(jsFile);
+    return { name, description: '', args: [], services };
+  });
+}
+
+/**
+ * Build the types section by cross-referencing component/route usages.
+ */
+function buildTypes(routes, components, services) {
+  const typeMap = new Map();
+
+  function register(typeSlug, category, name) {
+    if (!typeMap.has(typeSlug)) {
+      typeMap.set(typeSlug, { routes: [], components: [], services: [], helpers: [], modifiers: [] });
+    }
+    typeMap.get(typeSlug)[category].push(name);
+  }
+
+  for (const r of routes) {
+    for (const t of r.types || []) register(t, 'routes', r.name);
+  }
+  for (const c of components) {
+    for (const t of c.types || []) register(t, 'components', c.name);
+  }
+
+  return [...typeMap.entries()].map(([slug, used_in]) => ({ slug, used_in }));
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+module.exports = async function pull(cwd) {
+  const appDir = path.join(cwd, 'app');
+  const configDir = path.join(cwd, 'config');
+  const outputFile = path.join(configDir, 'storylang.json');
+
+  if (!fs.existsSync(appDir)) {
+    throw new Error(
+      `Could not find app/ directory at ${appDir}. ` +
+      `Make sure you are running storylang from the root of your Ember project.`
+    );
+  }
+
+  console.log('📖  storylang pull — scanning project files…\n');
+
+  const components = buildComponents(appDir);
+  const routes = buildRoutes(appDir);
+  const services = buildServices(appDir);
+  const helpers = buildHelpers(appDir);
+  const modifiers = buildModifiers(appDir);
+  const types = buildTypes(routes, components, services);
+
+  // Merge with existing storylang.json so hand-written fields are preserved
+  let existing = {};
+  if (fs.existsSync(outputFile)) {
+    try {
+      existing = JSON.parse(fs.readFileSync(outputFile, 'utf8'));
+    } catch (_) {
+      // corrupt file — start fresh
+    }
+  }
+
+  const merged = {
+    implementation_approach: existing.implementation_approach || '',
+    types: mergeByKey(existing.types || [], types, 'slug'),
+    components: mergeByKey(existing.components || [], components, 'name'),
+    routes: mergeByKey(existing.routes || [], routes, 'name'),
+    services: mergeByKey(existing.services || [], services, 'name'),
+    helpers: mergeByKey(existing.helpers || [], helpers, 'name'),
+    modifiers: mergeByKey(existing.modifiers || [], modifiers, 'name'),
+  };
+
+  if (!fs.existsSync(configDir)) fs.mkdirSync(configDir, { recursive: true });
+  fs.writeFileSync(outputFile, JSON.stringify(merged, null, 2) + '\n', 'utf8');
+
+  console.log(`✅  config/storylang.json updated`);
+  console.log(`    routes:     ${routes.length}`);
+  console.log(`    components: ${components.length}`);
+  console.log(`    services:   ${services.length}`);
+  console.log(`    helpers:    ${helpers.length}`);
+  console.log(`    modifiers:  ${modifiers.length}`);
+  console.log(`    types:      ${types.length}`);
+};
+
+/**
+ * Merge two arrays by a key, preferring scanned values for structural fields
+ * but keeping existing hand-written description / implementation_approach fields.
+ */
+function mergeByKey(existing, scanned, key) {
+  const existingMap = new Map(existing.map((e) => [e[key], e]));
+  const scannedMap = new Map(scanned.map((s) => [s[key], s]));
+
+  const allKeys = new Set([...existingMap.keys(), ...scannedMap.keys()]);
+  const result = [];
+  for (const k of allKeys) {
+    const e = existingMap.get(k) || {};
+    const s = scannedMap.get(k) || {};
+    // scanned data wins for structural fields; preserve description from existing
+    result.push({ ...s, description: e.description || s.description || '' });
+  }
+  return result;
+}

package/lib/storylang/push.js

@@ -0,0 +1,403 @@
+'use strict';
+
+/**
+ * storylang push [--overwrite / -o]
+ *
+ * Reads config/storylang.json and generates missing (or all, when -o is set)
+ * Ember project files: routes, controllers, components, services, helpers,
+ * modifiers, and their corresponding templates where applicable.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// ---------------------------------------------------------------------------
+// Small utilities
+// ---------------------------------------------------------------------------
+
+function toPascalCase(str) {
+  return str
+    .split(/[-/]/)
+    .map((p) => p.charAt(0).toUpperCase() + p.slice(1))
+    .join('');
+}
+
+function toCamelCase(str) {
+  const pascal = toPascalCase(str);
+  return pascal.charAt(0).toLowerCase() + pascal.slice(1);
+}
+
+function ensureDir(filePath) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+}
+
+/**
+ * Write a file only if it does not exist (or overwrite=true).
+ * Returns true if the file was actually written.
+ */
+function writeFile(filePath, content, overwrite) {
+  if (!overwrite && fs.existsSync(filePath)) return false;
+  ensureDir(filePath);
+  fs.writeFileSync(filePath, content, 'utf8');
+  return true;
+}
+
+// ---------------------------------------------------------------------------
+// Template generators
+// ---------------------------------------------------------------------------
+
+/**
+ * Route JS file
+ */
+function routeJs(def) {
+  const className = toPascalCase(def.name) + 'Route';
+  const services = def.services || [];
+  const getVars = def.get_vars || [];
+  const actions = def.actions || [];
+
+  const serviceImports = services.length ? `import { service } from '@ember/service';\n` : '';
+  const actionImport = actions.length ? `import { action } from '@ember/object';\n` : '';
+
+  const serviceProps = services.map((s) => `  @service ${toCamelCase(s)};`).join('\n');
+
+  const queryParamsBlock =
+    getVars.length
+      ? `\n  queryParams = {\n${getVars
+          .map((v) => {
+            const key = Object.keys(v)[0];
+            return `    ${key}: { refreshModel: true },`;
+          })
+          .join('\n')}\n  };\n`
+      : '';
+
+  const modelArgs = getVars.length ? 'params' : '';
+  const modelBody =
+    getVars.length
+      ? `    // TODO: use params to filter/paginate\n    // return await this.store.query('type-name', { page: { offset: 0, limit: 10 } });`
+      : `    // TODO: return model data\n    // return await this.store.query('type-name', {});`;
+
+  const actionMethods = actions
+    .map(
+      (a) =>
+        `\n  @action\n  async ${a}() {\n    // TODO: implement ${a}\n  }`
+    )
+    .join('\n');
+
+  return `import Route from '@ember/routing/route';
+${serviceImports}${actionImport}
+export default class ${className} extends Route {
+${serviceProps ? serviceProps + '\n' : ''}${queryParamsBlock}
+  async model(${modelArgs}) {
+${modelBody}
+  }
+${actionMethods}
+}
+`;
+}
+
+/**
+ * Controller JS file (minimal — logic lives in components)
+ */
+function controllerJs(def) {
+  const className = toPascalCase(def.name) + 'Controller';
+  return `import Controller from '@ember/controller';
+
+export default class ${className} extends Controller {
+  // Minimal controller — keep business logic in components and services.
+}
+`;
+}
+
+/**
+ * Route HBS template
+ */
+function routeHbs(def) {
+  const components = def.components || [];
+  const inner = components.length
+    ? components.map((c) => `  <${toPascalCase(c)} />`).join('\n')
+    : '  {{outlet}}';
+  return `<div class="route-${def.name}">\n${inner}\n</div>\n`;
+}
+
+/**
+ * Component JS file
+ */
+function componentJs(def) {
+  const className = toPascalCase(def.name) + 'Component';
+  const trackedVars = def.tracked_vars || [];
+  const actions = def.actions || [];
+  const services = def.services || [];
+
+  const hasTracked = trackedVars.length > 0;
+  const hasActions = actions.length > 0;
+  const hasServices = services.length > 0;
+
+  const imports = [
+    `import Component from '@glimmer/component';`,
+    hasTracked ? `import { tracked } from '@glimmer/tracking';` : '',
+    hasActions ? `import { action } from '@ember/object';` : '',
+    hasServices ? `import { service } from '@ember/service';` : '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  const serviceProps = services.map((s) => `  @service ${toCamelCase(s)};`).join('\n');
+  const trackedProps = trackedVars
+    .map((v) => {
+      const [name, type] = Object.entries(v)[0];
+      const defaultVal = defaultForType(type);
+      return `  @tracked ${name} = ${defaultVal};`;
+    })
+    .join('\n');
+
+  const actionMethods = actions
+    .map(
+      (a) =>
+        `\n  @action\n  async ${a}() {\n    // TODO: implement ${a}\n  }`
+    )
+    .join('\n');
+
+  return `${imports}
+
+export default class ${className} extends Component {
+${serviceProps ? serviceProps + '\n' : ''}${trackedProps ? trackedProps + '\n' : ''}${actionMethods}
+}
+`;
+}
+
+function defaultForType(type) {
+  switch (type) {
+    case 'bool': return 'false';
+    case 'int': return '0';
+    case 'array': return '[]';
+    case 'object': return 'null';
+    default: return 'null';
+  }
+}
+
+/**
+ * Component HBS template
+ */
+function componentHbs(def) {
+  const type = def.type || 'component';
+  const inheritedArgs = def.inherited_args || [];
+
+  // Pick a sensible wrapper element/class based on component type
+  const wrapperClass = bootstrapClass(type);
+  const argDisplay = inheritedArgs
+    .filter((a) => {
+      const key = Object.keys(a)[0];
+      const argType = Object.values(a)[0];
+      return argType === 'var';
+    })
+    .map((a) => {
+      const key = Object.keys(a)[0];
+      return `  <p>{{@${key}}}</p>`;
+    })
+    .join('\n');
+
+  return `<div class="${wrapperClass}">
+${argDisplay || '  {{! TODO: add template content }}'}
+</div>
+`;
+}
+
+function bootstrapClass(type) {
+  const map = {
+    card: 'card',
+    table: 'table-responsive',
+    modal: 'modal',
+    accordion: 'accordion',
+    alert: 'alert',
+    badge: 'badge',
+    toast: 'toast',
+    navbar: 'navbar navbar-expand-lg',
+    nav: 'nav',
+    tab: 'nav nav-tabs',
+    breadcrumb: 'breadcrumb',
+    'list-group': 'list-group',
+    button: 'btn btn-primary',
+    'button-group': 'btn-group',
+    dropdown: 'dropdown',
+    collapse: 'collapse',
+    offcanvas: 'offcanvas',
+    pagination: 'pagination',
+    progress: 'progress',
+    spinner: 'spinner-border',
+  };
+  return map[type] || 'container';
+}
+
+/**
+ * Service JS file
+ */
+function serviceJs(def) {
+  const className = toPascalCase(def.name) + 'Service';
+  const trackedVars = def.tracked_vars || [];
+  const actions = def.actions || [];
+  const services = def.services || [];
+
+  const hasTracked = trackedVars.length > 0;
+  const hasActions = actions.length > 0;
+  const hasServices = services.length > 0;
+
+  const imports = [
+    `import Service from '@ember/service';`,
+    hasTracked ? `import { tracked } from '@glimmer/tracking';` : '',
+    hasActions ? `import { action } from '@ember/object';` : '',
+    hasServices ? `import { service } from '@ember/service';` : '',
+  ]
+    .filter(Boolean)
+    .join('\n');
+
+  const serviceProps = services.map((s) => `  @service ${toCamelCase(s)};`).join('\n');
+  const trackedProps = trackedVars
+    .map((v) => {
+      const [name, type] = Object.entries(v)[0];
+      return `  @tracked ${name} = ${defaultForType(type)};`;
+    })
+    .join('\n');
+
+  const actionMethods = actions
+    .map(
+      (a) =>
+        `\n  async ${a}() {\n    // TODO: implement ${a}\n  }`
+    )
+    .join('\n');
+
+  return `${imports}
+
+export default class ${className} extends Service {
+${serviceProps ? serviceProps + '\n' : ''}${trackedProps ? trackedProps + '\n' : ''}${actionMethods}
+}
+`;
+}
+
+/**
+ * Helper JS file
+ */
+function helperJs(def) {
+  const fnName = toCamelCase(def.name);
+  const argNames = (def.args || []).map((a) => Object.keys(a)[0]);
+  const positional = argNames.length ? `[${argNames.join(', ')}]` : '[]';
+  const description = def.description ? `// ${def.description}\n` : '';
+
+  return `import { helper } from '@ember/component/helper';
+
+${description}export default helper(function ${fnName}(${positional}/*, namedArgs*/) {
+  // TODO: implement ${def.name}
+  return '';
+});
+`;
+}
+
+/**
+ * Modifier JS file
+ */
+function modifierJs(def) {
+  const argNames = (def.args || []).map((a) => Object.keys(a)[0]);
+  const positional = argNames.length ? `[${argNames.join(', ')}]` : '[]';
+  const services = def.services || [];
+  const description = def.description ? `// ${def.description}\n` : '';
+  const serviceImports = services.length ? `import { service } from '@ember/service';\n` : '';
+
+  return `import { modifier } from 'ember-modifier';
+${serviceImports}
+${description}export default modifier((element, ${positional}/*, namedArgs*/) => {
+  // TODO: implement ${def.name} modifier
+
+  return () => {
+    // cleanup
+  };
+});
+`;
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+module.exports = async function push(cwd, { overwrite = false } = {}) {
+  const configFile = path.join(cwd, 'config', 'storylang.json');
+
+  if (!fs.existsSync(configFile)) {
+    throw new Error(
+      `config/storylang.json not found at ${configFile}.\n` +
+      `Run "storylang pull" first, or create config/storylang.json manually.`
+    );
+  }
+
+  let spec;
+  try {
+    spec = JSON.parse(fs.readFileSync(configFile, 'utf8'));
+  } catch (e) {
+    throw new Error(`Failed to parse config/storylang.json: ${e.message}`);
+  }
+
+  const appDir = path.join(cwd, 'app');
+  const mode = overwrite ? '(overwrite mode)' : '(skip existing)';
+  console.log(`🚀  storylang push ${mode}\n`);
+
+  const stats = { written: 0, skipped: 0 };
+
+  function write(filePath, content) {
+    const wrote = writeFile(filePath, content, overwrite);
+    if (wrote) {
+      console.log(`  ✔  ${path.relative(cwd, filePath)}`);
+      stats.written++;
+    } else {
+      console.log(`  –  ${path.relative(cwd, filePath)} (skipped — already exists)`);
+      stats.skipped++;
+    }
+  }
+
+  // ── Routes ──────────────────────────────────────────────────────────────
+  if (spec.routes && spec.routes.length) {
+    console.log('Routes:');
+    for (const def of spec.routes) {
+      if (!def.name) continue;
+      write(path.join(appDir, 'routes', `${def.name}.js`), routeJs(def));
+      write(path.join(appDir, 'controllers', `${def.name}.js`), controllerJs(def));
+      write(path.join(appDir, 'templates', `${def.name}.hbs`), routeHbs(def));
+    }
+  }
+
+  // ── Components ──────────────────────────────────────────────────────────
+  if (spec.components && spec.components.length) {
+    console.log('\nComponents:');
+    for (const def of spec.components) {
+      if (!def.name) continue;
+      write(path.join(appDir, 'components', `${def.name}.js`), componentJs(def));
+      write(path.join(appDir, 'components', `${def.name}.hbs`), componentHbs(def));
+    }
+  }
+
+  // ── Services ─────────────────────────────────────────────────────────────
+  if (spec.services && spec.services.length) {
+    console.log('\nServices:');
+    for (const def of spec.services) {
+      if (!def.name) continue;
+      write(path.join(appDir, 'services', `${def.name}.js`), serviceJs(def));
+    }
+  }
+
+  // ── Helpers ──────────────────────────────────────────────────────────────
+  if (spec.helpers && spec.helpers.length) {
+    console.log('\nHelpers:');
+    for (const def of spec.helpers) {
+      if (!def.name) continue;
+      write(path.join(appDir, 'helpers', `${def.name}.js`), helperJs(def));
+    }
+  }
+
+  // ── Modifiers ────────────────────────────────────────────────────────────
+  if (spec.modifiers && spec.modifiers.length) {
+    console.log('\nModifiers:');
+    for (const def of spec.modifiers) {
+      if (!def.name) continue;
+      write(path.join(appDir, 'modifiers', `${def.name}.js`), modifierJs(def));
+    }
+  }
+
+  console.log(`\n✅  Done — ${stats.written} file(s) written, ${stats.skipped} skipped.`);
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ember-tribe",
-  "version": "2.5.3",
+  "version": "2.6.1",
   "description": "The default blueprint for using Tribe API and Junction within EmberJS.",
   "keywords": [
     "ember-addon"
@@ -25,6 +25,9 @@
     "test:ember": "ember test",
     "test:ember-compatibility": "ember try:each"
   },
+  "bin": {
+    "storylang": "bin/storylang"
+  },
   "dependencies": {
     "ember-cli-babel": "^7.26.11",
     "ember-cli-htmlbars": "^6.0.1"
@@ -78,4 +81,4 @@
   "ember-addon": {
     "configPath": "tests/dummy/config"
   }
-}
+}