nowaikit 2.6.0 → 3.0.0

package/dist/prompts/capabilities/build-flow.js

@@ -0,0 +1,243 @@
+const capability = {
+    name: 'build-flow',
+    title: 'Build Flow',
+    description: 'Guided Flow Designer creation — triggers, actions, subflows, error handling, testing',
+    category: 'build',
+    arguments: [
+        {
+            name: 'description',
+            description: 'what the flow should do in plain language',
+            required: true,
+        },
+        {
+            name: 'trigger_type',
+            description: 'record, scheduled, application, inbound_email. Default: record',
+            required: false,
+        },
+        {
+            name: 'table',
+            description: 'target table for record-triggered flows',
+            required: false,
+        },
+    ],
+    recommendedTools: [
+        'query_records',
+        'list_flows',
+        'get_flow',
+        'trigger_flow',
+        'create_flow',
+        'create_subflow',
+        'list_business_rules',
+        'get_table_schema',
+    ],
+    buildPrompt(args = {}) {
+        const desc = args.description ?? '<not provided>';
+        const triggerType = args.trigger_type ?? 'record';
+        const table = args.table ?? '<not specified>';
+        return [
+            {
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: [
+                        '# Capability: Build Flow (Flow Designer)',
+                        '',
+                        '## ServiceNow Flow Designer — Platform Knowledge',
+                        '',
+                        '### Trigger Types',
+                        '- **Record:** fires on insert, update, or delete of a record on a specific table. Supports conditions (e.g., state changes to "Resolved"). Most common trigger type.',
+                        '- **Scheduled:** fires on a cron schedule (daily, weekly, custom). Used for batch processing, cleanup, periodic sync. Runs as the flow owner unless impersonation is configured.',
+                        '- **Application:** fires from a Script Action, Business Rule, or another flow via `sn_fd.FlowAPI.startFlow()`. Best for event-driven or decoupled architectures.',
+                        '- **Inbound Email:** fires when an email is received matching criteria (sender, subject regex, body contains). Used for email-to-ticket, approval via email.',
+                        '- **REST:** fires from an inbound REST API call. Useful for external system integrations, webhooks.',
+                        '',
+                        '### Action Types',
+                        '- **Create Record / Update Record / Delete Record:** CRUD operations on any table. Use dot-walking for reference field data.',
+                        '- **Look Up Records / Look Up Record:** query one or many records with conditions. Returns data pills for downstream use.',
+                        '- **Run Script:** inline server-side JavaScript. Has access to `fd_data` (flow data pills). Use sparingly — prefer built-in actions for maintainability.',
+                        '- **Call Subflow:** invoke a reusable subflow with input parameters. Outputs from the subflow are available as data pills.',
+                        '- **Send Notification:** fire a notification with dynamic recipients, subject, and body.',
+                        '- **Log:** write to sys_log for debugging and audit trail. Include flow context in log messages.',
+                        '- **If / Else If / Else:** conditional branching based on data pill values, record conditions, or script results.',
+                        '- **For Each:** iterate over a list of records returned from Look Up Records.',
+                        '- **Wait For:** pause flow execution until a condition is met (record update, duration elapsed, specific date/time). Creates a `wf_context` record.',
+                        '- **Ask for Approval:** request approval from users/groups with configurable approval rules (anyone, everyone, percentage).',
+                        '- **Make REST Call:** outbound HTTP request with dynamic URL, headers, body. Supports OAuth, Basic Auth, mutual TLS.',
+                        '- **Transform:** data transformation and mapping between data pills.',
+                        '',
+                        '### Error Handling Patterns',
+                        '- **Try / Catch:** wrap risky actions in a try block. The catch block receives error details (message, action that failed). Always include a catch for external calls (REST, Script).',
+                        '- **Rollback Actions:** in the catch block, undo partially completed work (delete created records, revert field changes).',
+                        '- **Error Output:** flows can define error outputs so callers (parent flows, subflows) can handle failures gracefully.',
+                        '- **Logging in Catch:** always log the error with full context (flow name, trigger record, action name, error message) for troubleshooting.',
+                        '- **Retry Pattern:** for transient failures (REST timeout, lock contention), implement retry with a Wait action followed by re-execution of the failed action.',
+                        '',
+                        '### Flow Variables & Data Pills',
+                        '- **Trigger data pills:** `Trigger Record` and its fields are available as data pills throughout the flow.',
+                        '- **Action outputs:** each action produces output data pills (created record sys_id, lookup results, script return values).',
+                        '- **Flow variables:** define typed inputs/outputs on the flow for parameterization. Inputs can be set by callers (Application trigger, parent flow).',
+                        '- **Inline scripts** access data pills via the `fd_data` object.',
+                        '- **Dot-walking:** reference field data pills support dot-walking (e.g., `Trigger Record.assigned_to.manager.email`).',
+                        '',
+                        '### Subflow Design Principles',
+                        '- Extract reusable logic into subflows: notification patterns, approval chains, record creation templates.',
+                        '- Subflows have typed inputs and outputs — define them clearly for reuse.',
+                        '- Subflows can be called from any flow, reducing duplication.',
+                        '- Keep subflows focused on a single responsibility.',
+                        '- Version subflows carefully — changes affect all calling flows.',
+                        '',
+                        '### Performance Considerations',
+                        '- Avoid Look Up Records inside For Each loops (N+1 pattern). Instead, look up all needed records before the loop.',
+                        '- Use conditions on the trigger to minimize unnecessary flow executions.',
+                        '- Prefer built-in actions over Run Script for better platform optimization.',
+                        '- Long-running flows (with Wait actions) consume `wf_context` records — monitor and clean up stale contexts.',
+                        '- Scheduled flows that process large datasets should use pagination (limit + offset) or batch subflows.',
+                        '',
+                        '### Testing Best Practices',
+                        '- Test with records that match AND do not match trigger conditions.',
+                        '- Test each conditional branch (If / Else If / Else).',
+                        '- Test error paths by simulating action failures (invalid record, REST endpoint down).',
+                        '- Test subflow inputs at boundary values (null, empty string, max length).',
+                        '- Use Flow Designer\'s built-in test feature for individual action verification.',
+                        '- For scheduled flows, test with the expected data volume to identify performance issues.',
+                        '',
+                        '---',
+                        '',
+                        `Starting flow build for: **${desc}**`,
+                        `Trigger type: **${triggerType}**`,
+                        table !== '<not specified>'
+                            ? `Table: **${table}**`
+                            : 'Table: to be determined from requirement analysis',
+                    ].join('\n'),
+                },
+            },
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Build a Flow Designer flow for the following requirement:`,
+                        `**Requirement:** ${desc}`,
+                        `**Trigger type:** ${triggerType}`,
+                        `**Table:** ${table}`,
+                        '',
+                        'Follow these steps exactly:',
+                        '',
+                        '### Step 1 — Understand the Requirement',
+                        'Parse the requirement and identify:',
+                        '- **Trigger event:** what causes this flow to start (record insert/update/delete, schedule, application event, inbound email).',
+                        `- **Trigger type:** ${triggerType}. Validate this is appropriate for the requirement; if not, recommend the correct trigger type and explain why.`,
+                        '- **Trigger conditions:** what conditions must be met on the trigger record (e.g., state changes from X to Y, priority = 1, category = "Hardware").',
+                        table !== '<not specified>'
+                            ? `- **Table:** ${table}. Use **get_table_schema** to verify the table exists and understand its fields, types, and relationships.`
+                            : '- **Table:** determine the correct table from the requirement. Use **get_table_schema** to verify it.',
+                        '- **Expected outcome:** what should happen when the flow completes successfully.',
+                        '- **Error scenarios:** what could go wrong and how should errors be handled.',
+                        '',
+                        '### Step 2 — Check Existing Flows for Conflicts',
+                        `Use **list_flows** to find all active flows${table !== '<not specified>' ? ` on the "${table}" table` : ''}. For each existing flow, note:`,
+                        '- Flow name, trigger type, trigger conditions.',
+                        '- Whether it overlaps with the new requirement (same trigger event + condition).',
+                        '- Whether it could conflict (competing updates to the same fields, contradictory actions).',
+                        '- Whether the new requirement could be met by modifying an existing flow instead of creating a new one.',
+                        '',
+                        'Also check **list_business_rules** on the same table — business rules on the same trigger event may conflict with or duplicate flow logic.',
+                        '',
+                        'If conflicts are found, recommend a resolution strategy before proceeding.',
+                        '',
+                        '### Step 3 — Design the Flow Structure',
+                        'Design the complete flow architecture before building:',
+                        '',
+                        '```',
+                        'FLOW: [Flow Name]',
+                        '  TRIGGER: [type] on [table] when [conditions]',
+                        '  ',
+                        '  TRY:',
+                        '    1. [Action Type] — [description]',
+                        '       Input: [data pills / values]',
+                        '       Output: [data pill name]',
+                        '    ',
+                        '    2. IF [condition]:',
+                        '         2a. [Action] — [description]',
+                        '       ELSE:',
+                        '         2b. [Action] — [description]',
+                        '    ',
+                        '    3. [Action] — [description]',
+                        '    ...',
+                        '  ',
+                        '  CATCH:',
+                        '    C1. Log Error — [error message with context]',
+                        '    C2. [Rollback Action] — [undo partial work]',
+                        '    C3. [Notification] — alert admin/support',
+                        '  ',
+                        '  OUTPUTS:',
+                        '    - [output_name]: [type] — [description]',
+                        '```',
+                        '',
+                        'For each action, specify:',
+                        '- The exact action type (Create Record, Update Record, Look Up Records, Run Script, etc.).',
+                        '- Input data pills and static values.',
+                        '- Output data pill names for downstream use.',
+                        '- Conditions for branching actions.',
+                        '',
+                        '### Step 4 — Identify Subflow Opportunities',
+                        'Determine if any logic should be extracted into subflows:',
+                        '- **Reusable patterns:** notification sequences, approval chains, record creation templates used in multiple flows.',
+                        '- **Complex sub-processes:** approval with escalation, multi-step provisioning, data validation suites.',
+                        '- **Testability:** isolated subflows are easier to test independently.',
+                        '',
+                        'For each subflow, define:',
+                        '- Name and description.',
+                        '- Typed inputs (name, type, mandatory flag).',
+                        '- Typed outputs (name, type).',
+                        '- Internal action sequence.',
+                        '',
+                        'Use **create_subflow** for each identified subflow before creating the main flow.',
+                        '',
+                        '### Step 5 — Generate Flow with Error Handling',
+                        'Build the flow using **create_flow** with:',
+                        '- Descriptive name following naming convention: `[Scope] - [Table] - [Purpose]` (e.g., "ITIL - Incident - Auto-Assign Critical").',
+                        '- Clear description explaining trigger, purpose, and expected outcomes.',
+                        '- Proper trigger configuration with conditions.',
+                        '- All actions in sequence with data pill bindings.',
+                        '- **Try/Catch wrapping** for all external calls, script actions, and record operations that could fail.',
+                        '- Rollback actions in the catch block to undo partial work.',
+                        '- Error logging with full context (flow name, trigger record sys_id, failed action, error message).',
+                        '- Error notification to administrators for critical failures.',
+                        '',
+                        'Validate:',
+                        '- No hardcoded sys_ids — use Look Up Record actions or flow inputs.',
+                        '- No N+1 patterns (Look Up Records inside For Each without prior aggregation).',
+                        '- All reference field data pills use dot-walking correctly.',
+                        '- Wait actions (if any) have appropriate timeout configuration.',
+                        '- Approval actions (if any) have correct rejection handling.',
+                        '',
+                        '### Step 6 — Create the Flow',
+                        'Use **create_flow** (and **create_subflow** for any subflows) to create the artifacts in ServiceNow. Report:',
+                        '- Flow sys_id and name.',
+                        '- Subflow sys_id(s) and name(s), if any.',
+                        '- Total action count and structure summary.',
+                        '',
+                        '### Step 7 — Suggest Test Scenarios',
+                        'Provide a comprehensive test matrix:',
+                        '',
+                        '| # | Scenario | Trigger Setup | Expected Flow Behavior | Expected Outcome |',
+                        '|---|----------|---------------|------------------------|------------------|',
+                        '',
+                        'Include at minimum:',
+                        '- **Happy path:** trigger fires, all conditions met, flow completes successfully end-to-end.',
+                        '- **Condition mismatch:** trigger fires but conditions are NOT met — flow should not execute.',
+                        '- **Branching:** test each conditional branch (If/Else) with appropriate trigger data.',
+                        '- **Error path:** simulate a failure in a critical action — verify catch block executes, rollback happens, notification is sent.',
+                        '- **Subflow isolation:** test each subflow independently with boundary inputs.',
+                        '- **Concurrency:** if applicable, test what happens when multiple flow instances run simultaneously on related records.',
+                        '- **Performance:** test with realistic data volume to verify the flow completes within acceptable time.',
+                        '- **Idempotency:** verify the flow produces correct results if triggered multiple times for the same record.',
+                    ].join('\n'),
+                },
+            },
+        ];
+    },
+};
+export default capability;
+//# sourceMappingURL=build-flow.js.map

package/dist/prompts/capabilities/build-flow.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-flow.js","sourceRoot":"","sources":["../../../src/prompts/capabilities/build-flow.ts"],"names":[],"mappings":"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"}

package/dist/prompts/capabilities/build-portal.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityDefinition } from '../types.js';
+declare const capability: CapabilityDefinition;
+export default capability;
+//# sourceMappingURL=build-portal.d.ts.map

package/dist/prompts/capabilities/build-portal.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-portal.d.ts","sourceRoot":"","sources":["../../../src/prompts/capabilities/build-portal.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,QAAA,MAAM,UAAU,EAAE,oBAyPjB,CAAC;AAEF,eAAe,UAAU,CAAC"}

package/dist/prompts/capabilities/build-portal.js

@@ -0,0 +1,250 @@
+const capability = {
+    name: 'build-portal',
+    title: 'Build Service Portal Widget',
+    description: 'Guided Service Portal widget creation — server script, client controller, HTML template, CSS, data brokers',
+    category: 'build',
+    arguments: [
+        {
+            name: 'description',
+            description: 'what the widget should do in plain language',
+            required: true,
+        },
+        {
+            name: 'widget_name',
+            description: 'widget name / ID (e.g., my-custom-widget)',
+            required: false,
+        },
+        {
+            name: 'table',
+            description: 'primary table the widget interacts with',
+            required: false,
+        },
+    ],
+    recommendedTools: [
+        'query_records',
+        'get_table_schema',
+        'list_portal_widgets',
+        'get_portal_widget',
+        'create_portal_widget',
+        'update_portal_widget',
+    ],
+    buildPrompt(args = {}) {
+        const desc = args.description ?? '<not provided>';
+        const widgetName = args.widget_name ?? '<auto-generate from description>';
+        const table = args.table ?? '<not specified>';
+        return [
+            {
+                role: 'assistant',
+                content: {
+                    type: 'text',
+                    text: [
+                        '# Capability: Build Service Portal Widget',
+                        '',
+                        '## Service Portal Widget Architecture — Platform Knowledge',
+                        '',
+                        '### Widget Lifecycle',
+                        '1. **Server script executes first** (runs on the server as a Rhino script). Sets `data` object properties that are sent to the client.',
+                        '2. **Client controller executes** (AngularJS 1.x). Receives `data` via `$scope.data` (aliased as `c.data` in the template via `controllerAs: \'c\'`).',
+                        '3. **HTML template renders** using Angular directives and `c.data` / `c.server` bindings.',
+                        '4. **CSS/SCSS** styles the widget, scoped to the widget instance.',
+                        '5. **Client interactions** can call back to the server via `c.server.update()` which re-executes the server script with `input` object containing client-sent data.',
+                        '',
+                        '### Server Script Patterns',
+                        '- **`data` object:** the bridge between server and client. Set `data.myProperty = value` and access it as `c.data.myProperty` in the template.',
+                        '- **`input` object:** populated when the client calls `c.server.update()`. Check `if (input)` to differentiate initial load from client callbacks.',
+                        '- **`options` object:** widget instance options configured in the Page Editor.',
+                        '- **`$sp` API:**',
+                        '  - `$sp.getParameter(name)` — read URL parameters.',
+                        '  - `$sp.getPortalRecord()` — get the current portal\'s GlideRecord.',
+                        '  - `$sp.getUser()` — get current user info (sys_id, name, roles).',
+                        '  - `$sp.getStream(table, sys_id)` — get activity stream for a record.',
+                        '  - `$sp.getRecordDisplayValues(data, gr, fields)` — bulk-extract display values.',
+                        '  - `$sp.getWidget(widgetId, options)` — get embedded widget instance.',
+                        '  - `$sp.getValues(data, gr, fields)` — bulk-extract raw values.',
+                        '- **GlideRecord queries:** use standard GlideRecord in server script. Apply `addEncodedQuery()` for complex filters. Always check `canRead()` before exposing data.',
+                        '- **GlideQuery:** modern alternative — `new GlideQuery(table).where(field, value).select(fields).toArray(limit)`. Cleaner, chainable, but check instance version support.',
+                        '',
+                        '### Client Controller Patterns',
+                        '- **`$scope.data`** (or `c.data`): read-only mirror of server data. Modify `c.data` and call `c.server.update()` to sync back.',
+                        '- **`c.server.update()`:** sends `c.data` to the server script as `input`. Returns a promise. Use `.then(function(response) { c.data = response.data; })` to handle the response.',
+                        '- **`c.server.get(params)`:** sends arbitrary params object to the server without merging with `c.data`.',
+                        '- **`spUtil` service:**',
+                        '  - `spUtil.update($scope)` — alternative to `c.server.update()` with automatic `$scope.data` binding.',
+                        '  - `spUtil.get(widgetId, options)` — dynamically load a widget.',
+                        '  - `spUtil.addInfoMessage(msg)` / `spUtil.addErrorMessage(msg)` — toast notifications.',
+                        '  - `spUtil.addTrivialMessage(msg)` — subtle notification.',
+                        '  - `spUtil.recordWatch($scope, table, filter, callback)` — real-time record updates via Ambient Message.',
+                        '- **`$rootScope.$broadcast` / `$on`:** inter-widget communication. Use custom events (e.g., `$rootScope.$broadcast(\'my-widget.data-changed\', payload)`).',
+                        '- **`$location` service:** read/manipulate URL for routing within the portal.',
+                        '- **`$timeout` service:** use instead of `setTimeout` for Angular digest-safe delays.',
+                        '',
+                        '### HTML Template Patterns',
+                        '- **Binding:** use `{{c.data.field}}` for interpolation, `ng-bind="c.data.field"` for safer XSS-free rendering.',
+                        '- **Lists:** `ng-repeat="item in c.data.items track by item.sys_id"` — always use `track by` for performance.',
+                        '- **Conditionals:** `ng-if="c.data.showSection"` (removes DOM) vs `ng-show` (hides with CSS).',
+                        '- **Forms:** `ng-model="c.data.formField"` for two-way binding. Use `ng-submit="c.submitForm()"` on `<form>`.',
+                        '- **Events:** `ng-click="c.doAction(item)"`, `ng-change="c.onFieldChange()"`, `ng-keypress`.',
+                        '- **Embedded widgets:** `<sp-widget widget="c.data.embeddedWidget"></sp-widget>`.',
+                        '- **Accessibility:** always include `aria-label`, `role`, `tabindex` on interactive elements. Use semantic HTML (`<button>`, `<a>`, `<nav>`).',
+                        '- **Localization:** use `${gs.getMessage("key")}` in server script or `{{::c.data.translatedLabel}}` — never hardcode user-facing strings.',
+                        '',
+                        '### CSS/SCSS Patterns',
+                        '- Widgets get **scoped CSS** — styles apply only within the widget\'s DOM boundary.',
+                        '- Use **BEM naming:** `.widget-name__element--modifier`.',
+                        '- Use **ServiceNow SCSS variables:** `$brand-primary`, `$brand-success`, `$brand-danger`, `$text-color`, `$panel-bg`, etc.',
+                        '- **Responsive breakpoints:** use `@media (max-width: 768px)` for mobile. Portal uses Bootstrap 3 grid (`col-xs-`, `col-sm-`, `col-md-`, `col-lg-`).',
+                        '- Avoid `!important` — use specificity instead.',
+                        '- Avoid absolute positioning unless necessary — prefer flexbox.',
+                        '',
+                        '### Security Considerations',
+                        '- **XSS prevention:** ALWAYS use `ng-bind` instead of `{{}}` for user-generated content. Never use `ng-bind-html` with unsanitized data. If HTML rendering is required, sanitize with `$sce.trustAsHtml()` only after server-side sanitization.',
+                        '- **ACL enforcement:** server script runs with the current user\'s session. GlideRecord queries respect ACLs by default. Do NOT use `GlideRecordSecure` (it is for background scripts, not portal widgets).',
+                        '- **Input validation:** validate all `input` fields in the server script before processing. Never trust client data.',
+                        '- **Role checks:** use `gs.hasRole()` in server script, NOT in the client controller (client-side role checks can be bypassed).',
+                        '- **SQL injection:** always use GlideRecord API methods — never concatenate strings into `addEncodedQuery()`.',
+                        '',
+                        '### Widget Options',
+                        '- Define configurable options (title, table, filter, show/hide sections) so the widget is reusable across pages.',
+                        '- Access via `options.my_option` in server script.',
+                        '- Option types: String, Integer, Boolean, Reference, Choice, Field List.',
+                        '',
+                        '### Data Brokers',
+                        '- Alternative to server scripts for data retrieval in newer portal pages.',
+                        '- Types: Table, REST, Script.',
+                        '- Advantages: cacheable, shareable between widgets, GraphQL-like field selection.',
+                        '',
+                        '---',
+                        '',
+                        `Starting widget build for: **${desc}**`,
+                        widgetName !== '<auto-generate from description>'
+                            ? `Widget name: **${widgetName}**`
+                            : 'Widget name: will be generated from requirement',
+                        table !== '<not specified>'
+                            ? `Primary table: **${table}**`
+                            : 'Primary table: to be determined from requirement analysis',
+                    ].join('\n'),
+                },
+            },
+            {
+                role: 'user',
+                content: {
+                    type: 'text',
+                    text: [
+                        `Build a Service Portal widget for the following requirement:`,
+                        `**Requirement:** ${desc}`,
+                        `**Widget name:** ${widgetName}`,
+                        `**Table:** ${table}`,
+                        '',
+                        'Follow these steps exactly:',
+                        '',
+                        '### Step 1 — Understand the Requirement',
+                        'Analyze the requirement and determine:',
+                        '- **Data needs:** what data the widget displays or manipulates. Which table(s) and fields are involved.',
+                        '- **User interaction:** what actions can the user perform (view, filter, create, edit, submit, approve).',
+                        '- **Target users:** who uses this widget (end users, fulfillers, managers). This affects data scoping and ACL considerations.',
+                        table !== '<not specified>'
+                            ? `- **Table:** ${table}. Use **get_table_schema** to understand its fields, types, and reference relationships.`
+                            : '- **Table:** determine the correct table(s). Use **get_table_schema** to verify.',
+                        '- **Widget context:** where will this widget live (main content, sidebar, modal, embedded in another widget).',
+                        '',
+                        '### Step 2 — Check Existing Widgets for Reuse',
+                        'Use **list_portal_widgets** to find widgets with similar functionality. For each candidate:',
+                        '- Review its server script, client controller, and template.',
+                        '- Assess whether it can be reused directly, extended via options, or used as a starting template.',
+                        '- If a suitable widget exists, recommend using or cloning it instead of building from scratch.',
+                        '',
+                        '### Step 3 — Design Widget Architecture',
+                        'Plan the widget structure before coding:',
+                        '',
+                        '```',
+                        `WIDGET: ${widgetName !== '<auto-generate from description>' ? widgetName : '[generated-name]'}`,
+                        '  SERVER SCRIPT:',
+                        '    - data.xxx = [description of each data property]',
+                        '    - input handling: [what client callbacks are supported]',
+                        '  CLIENT CONTROLLER:',
+                        '    - c.methodName() — [description of each method]',
+                        '    - $scope.$on events — [inter-widget communication]',
+                        '  HTML TEMPLATE:',
+                        '    - [layout description: header, body, footer]',
+                        '    - [list of Angular directives used]',
+                        '  CSS:',
+                        '    - [responsive behavior]',
+                        '    - [key style patterns]',
+                        '  OPTIONS:',
+                        '    - [configurable options for reusability]',
+                        '```',
+                        '',
+                        '### Step 4 — Generate Server Script',
+                        'Write the server script following these requirements:',
+                        '- Set all `data` properties needed by the template.',
+                        '- Handle `input` callbacks from the client (check `if (input && input.action === "xxx")`).',
+                        '- Use `$sp` API for portal-specific operations.',
+                        '- Apply GlideRecord queries with proper encoded queries and field limits (`.setLimit()`, `.chooseWindow()` for pagination).',
+                        '- Check `gs.hasRole()` for any role-gated data.',
+                        '- Call `canRead()` on GlideRecords before exposing sensitive data.',
+                        '- Include JSDoc-style comments explaining each data property and input handler.',
+                        '- For embedded widgets, use `data.embeddedWidget = $sp.getWidget("widget-id", options)`.',
+                        '',
+                        '### Step 5 — Generate Client Controller',
+                        'Write the AngularJS client controller:',
+                        '- Inject only needed services: `$scope`, `spUtil`, `$location`, `$timeout`, `$rootScope`.',
+                        '- Define `c.server.update()` calls for each client-to-server action.',
+                        '- Use `.then()` promises on all async operations.',
+                        '- Implement `spUtil.recordWatch()` if real-time updates are needed.',
+                        '- Broadcast/listen for inter-widget events with `$rootScope.$broadcast` / `$scope.$on`.',
+                        '- Handle loading states: set `c.data.loading = true` before server calls, `false` in `.then()`.',
+                        '- Avoid direct DOM manipulation — use Angular directives and `c.data` bindings.',
+                        '',
+                        '### Step 6 — Generate HTML Template',
+                        'Write the Angular HTML template:',
+                        '- Use `ng-bind` instead of `{{}}` for user-generated content (XSS prevention).',
+                        '- Include `track by` on all `ng-repeat` directives.',
+                        '- Use semantic HTML elements (`<section>`, `<article>`, `<nav>`, `<button>`).',
+                        '- Add ARIA attributes on interactive elements: `aria-label`, `aria-expanded`, `aria-live` for dynamic regions.',
+                        '- Support keyboard navigation: `tabindex`, `ng-keypress` for keyboard-accessible actions.',
+                        '- Use Bootstrap 3 grid classes for responsive layout: `col-xs-12 col-sm-6 col-md-4`.',
+                        '- Show loading spinner during async operations: `<div ng-if="c.data.loading"><i class="fa fa-spinner fa-spin"></i></div>`.',
+                        '- Include empty-state messaging when no data is returned.',
+                        '',
+                        '### Step 7 — Generate SCSS',
+                        'Write the SCSS styles:',
+                        '- Follow BEM naming: `.widget-name__element--modifier`.',
+                        '- Use ServiceNow SCSS variables (`$brand-primary`, `$text-color`, `$panel-bg`) for theme consistency.',
+                        '- Implement responsive design with media queries.',
+                        '- Use flexbox for layout alignment.',
+                        '- Avoid inline styles in the template — use CSS classes.',
+                        '- Add hover/focus states for interactive elements.',
+                        '- Keep specificity low — avoid `!important` and deep nesting.',
+                        '',
+                        '### Step 8 — Security Review',
+                        'Audit the generated widget for security issues:',
+                        '- **XSS:** verify no unsanitized user input is rendered via `ng-bind-html` or `{{}}`. All user-generated content uses `ng-bind`.',
+                        '- **ACL bypass:** verify server script does not use `setWorkflow(false)` or bypass ACLs. All GlideRecord queries run with the user\'s session.',
+                        '- **Input validation:** verify all `input` fields from client callbacks are validated in the server script (type, length, allowed values).',
+                        '- **CSRF:** `c.server.update()` includes CSRF token automatically via the platform. No manual CSRF handling needed.',
+                        '- **Data exposure:** verify the server script does not send more data than the template needs (don\'t send entire GlideRecord objects).',
+                        '- **Role gates:** verify sensitive actions check `gs.hasRole()` in the server script, not just in the client.',
+                        '',
+                        '### Step 9 — Create the Widget',
+                        'Use **create_portal_widget** with:',
+                        '- Widget ID (kebab-case, descriptive).',
+                        '- Display name.',
+                        '- Server script, client controller, HTML template, and CSS.',
+                        '- Widget options schema if applicable.',
+                        '',
+                        'Report the sys_id of the created widget.',
+                        '',
+                        'Provide a summary of how to add the widget to a portal page:',
+                        '1. Navigate to Service Portal > Pages.',
+                        '2. Open the target page in Page Editor.',
+                        '3. Add a container/row/column if needed.',
+                        '4. Drag the widget into the column.',
+                        '5. Configure widget options in the instance editor.',
+                    ].join('\n'),
+                },
+            },
+        ];
+    },
+};
+export default capability;
+//# sourceMappingURL=build-portal.js.map

package/dist/prompts/capabilities/build-portal.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-portal.js","sourceRoot":"","sources":["../../../src/prompts/capabilities/build-portal.ts"],"names":[],"mappings":"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"}

package/dist/prompts/capabilities/build-rest-api.d.ts

@@ -0,0 +1,4 @@
+import type { CapabilityDefinition } from '../types.js';
+declare const capability: CapabilityDefinition;
+export default capability;
+//# sourceMappingURL=build-rest-api.d.ts.map

package/dist/prompts/capabilities/build-rest-api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"build-rest-api.d.ts","sourceRoot":"","sources":["../../../src/prompts/capabilities/build-rest-api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,aAAa,CAAC;AAExD,QAAA,MAAM,UAAU,EAAE,oBAsSjB,CAAC;AAEF,eAAe,UAAU,CAAC"}