Skip to content

AGENTS.md

Latest commit

 

History

History
175 lines (131 loc) · 4.29 KB

AGENTS.md

File metadata and controls

175 lines (131 loc) · 4.29 KB
Raw

AGENTS.md - Lando Pantheon Plugin

This document provides guidance for AI coding agents working in this repository.

Project Overview

This is @lando/pantheon, a Node.js Lando plugin that integrates with Pantheon hosting. It provides local development environments mimicking Pantheon's stack and commands to sync code, database, and files.

  • Language: JavaScript (CommonJS, not ES modules)
  • Node Version: >=20.0.0
  • Style Guide: Google JavaScript Style Guide (via ESLint)
  • Testing: Mocha + Chai

Build/Lint/Test Commands

npm run lint              # Run linter
npm run test:unit         # Run all unit tests with coverage
npm run test              # Run lint + unit tests together
npm run test:leia         # Run integration tests (requires Lando)

# Run a single test file
npx mocha --timeout 5000 test/auth.spec.js

# Run tests matching a pattern
npx mocha --timeout 5000 --grep "pattern" test/**/*.spec.js

Directory Structure

builders/   # Lando service builders (pantheon-*.js)
config/     # Configuration templates (.conf.tpl, .vcl, etc.)
lib/        # Core library code (auth, client, utils)
scripts/    # Shell scripts for containers
test/       # Unit tests (*.spec.js)
utils/      # Utility modules
examples/   # Leia fixtures. See examples/AGENTS.md — remote landobot sites use master, not main.

Code Style Guidelines

Strict Mode and Imports

Every file must start with 'use strict'; followed by imports:

'use strict';

// Modules
const _ = require('lodash');
const fs = require('fs');
const {someFunc} = require('./lib/utils');
  • Use const with require() (CommonJS)
  • External/built-in modules first, then local modules

Naming Conventions

Type Convention Examples
Variables camelCase siteInfo, configPath
Constants SCREAMING_SNAKE_CASE DRUSH_VERSION
Functions camelCase, get/is prefix getHash, isWordPressy
Classes PascalCase PantheonApiClient
Files kebab-case pantheon-mariadb.js

Formatting (ESLint enforced)

  • Indentation: 2 spaces
  • Max line length: 140 characters
  • Quotes: Single quotes
  • Semicolons: Required
  • Arrow parens: Omit when possible (x => x)

JSDoc Requirements

Function declarations MUST have JSDoc comments:

/**
 * Gets framework-specific tooling configuration
 * @param {string} framework - Framework type
 * @param {number} [drush=8] - Drush version
 * @return {Object} Tooling configuration
 */
const getTooling = (framework, drush = 8) => { };

Error Handling

try {
  await api.auth();
} catch (error) {
  throw (_.has(error, 'response.data')) ? new Error(error.response.data) : error;
}

Lodash Usage

This codebase heavily uses Lodash. Prefer Lodash methods:

_.get(options, 'search.version', '3')    // Safe property access
_.merge({}, config, options)              // Deep merge
_.has(err, 'response.data')               // Check property exists

Module Exports

module.exports = async (app, lando) => { };
module.exports = class PantheonApiClient { };
module.exports = {
  name: 'pantheon',
  builder: (parent, config) => class extends parent { },
};
exports.getPantheonConfig = () => { };

Comment Conventions

// Modules                    // Section headers
// @NOTE: explanation...      // Notes
// @TODO: task description    // TODOs

Testing Conventions

Test files: test/*.spec.js using Mocha + Chai:

'use strict';

const chai = require('chai');
chai.should();

describe('ModuleName', () => {
  describe('#methodName', () => {
    it('should do something expected', () => {
      result.should.equal(expected);
    });
  });
});

Key Dependencies

  • lodash - Utility functions (use extensively)
  • axios - HTTP client for Pantheon API
  • js-yaml - YAML parsing
  • @lando/* - Lando service plugins

Common Patterns

Path Handling

path.join(options.root, 'pantheon.yml')
path.resolve(__dirname, '..', 'config')

Builder Pattern

builder: (parent, config) => class LandoPantheon extends parent {
  constructor(id, options = {}) {
    options = _.merge({}, config, options, utils.getPantheonConfig());
    super(id, options);
  }
}