codeapp-js 1.0.1 → 1.1.0

package/AI/skills/office365-users/SKILL.md

@@ -5,37 +5,45 @@ description: "Use when: building or debugging Office 365 Users connector flows i
 
 # Office 365 Users Connector Guide
 
-> Agent limitation: do not use CLI commands directly from chat for Office 365 Users setup. Use the built-in Sync Connections and Deploy buttons instead.
+Do not use CLI PAC commands to get connecctor models or services,
+use `codeApp/dist/connectors/office365users.js` as the repo source of truth.
 
-## Core Rule
-
-The wrapper in `dev files/office365users.js` is the repo-local source of truth.
-
-- It uses `office365users` as the connector data-source name.
-- It includes inline metadata for the supported operations.
-- It preserves older naming compatibility, but the main search operation used by the wrapper is `SearchUserV2`.
 
 ## power.config.json
 
-Expose `office365users` in the connection reference `dataSources` array.
+Always read the current `power.config.json` before editing it.
+
+Ensure `"id": "/providers/Microsoft.PowerApps/apis/shared_office365users"` exists.
 
 ```json
-{
-  "connectionReferences": {
-    "usersConnection": {
+"connectionReferences": {
+  "office365users": {
       "id": "/providers/Microsoft.PowerApps/apis/shared_office365users",
       "displayName": "Office 365 Users",
-      "dataSources": ["office365users"],
+      "dataSources": [
+        "office365users"
+      ],
+      "authenticationType": null,
+      "sharedConnectionId": null,
       "dataSets": {}
     }
-  }
 }
 ```
 
-## Public Helper Surface
+Rules for editing `power.config.json`:
+
+- Preserve existing keys such as `sharedConnectionId`, `authenticationType`, and other working connection metadata.
+- If the app uses Dataverse environment variables, also load the environment-variables skill.
+
+## Core Rule
+
+Prefer the exported helper layer instead of wiring raw connector operations directly in app code.
 
-The wrapper exports:
+## Action Helper Surface
 
+- `callUsersOperation(operationName, parameters)`
+- `openUsersHttpRequest(options)`
+- `updateMyProfile(profile)`
 - `getMyProfile(options)`
 - `getUserProfile(userId, options)`
 - `getManager(userId, options)`
@@ -43,36 +51,33 @@ The wrapper exports:
 - `getMyTrendingDocuments(options)`
 - `getTrendingDocuments(userId, options)`
 - `getRelevantPeople(userId)`
-- `updateMyProfile(profile)`
 - `updateMyPhoto(bodyOrOptions, contentType)`
 - `getUserPhotoMetadata(userId)`
 - `getUserPhoto(userId)`
 - `searchForUsers(options)`
-- `openUsersHttpRequest(options)`
-- `callUsersOperation(operationName, parameters)`
 
-## Important Wrapper Behavior
+## Latest Action Defaults
 
-- `select` can be an array or a comma-separated string.
-- `getDirectReports(...)` supports `top` and select options.
-- `searchForUsers(...)` uses `searchTerm`, `top`, `isSearchTermRequired`, and `skipToken`.
-- `searchForUsers(...)` accepts `nextLink` and legacy `skip` as compatibility inputs that the wrapper converts into `skipToken`.
-- `UserPhoto_V2` returns `image/jpeg`.
+- Profile helpers default to the V2 profile and manager actions.
+- `getDirectReports(...)` defaults to `DirectReports_V2`.
+- `getUserPhoto(...)` uses `UserPhoto_V2`.
+- `searchForUsers(...)` uses `SearchUserV2`.
+- `searchForUsers(...)` accepts `nextLink` and `skip` aliases and converts them into `skipToken`.
 
-## Raw HTTP Calls
+## HTTP Escape Hatch
 
-`openUsersHttpRequest(...)` does not use the simple `headers` object shape directly.
+`openUsersHttpRequest(...)` maps friendly inputs to connector fields:
 
-The wrapper maps friendly inputs into connector fields:
+- `uri` -> `Uri`
+- `method` -> `Method`
+- `body` -> `Body`
+- `contentType` -> `ContentType`
+- `customHeaders[0..4]` -> `CustomHeader1..5`
 
-- `Uri`
-- `Method`
-- `Body`
-- `ContentType`
-- `CustomHeader1..5`
+Use this only when no helper exists for the action you need.
 
 ## Debugging
 
-- If search pagination is broken, verify the code is passing `skipToken` or `nextLink`, not `$skip`.
-- If HTTP requests fail, check whether the wrapper is being fed connector-style fields through `openUsersHttpRequest(...)` rather than raw fetch options.
-- Keep the existing helper names stable and widen input support instead of replacing them.
+- If search pagination fails, pass `skipToken` or `nextLink`, not `$skip`.
+- If HTTP requests fail, verify you are sending connector-style fields through `openUsersHttpRequest(...)`.
+- Keep helper names stable and widen alias support instead of introducing another wrapper.

package/AI/skills/sharepoint/SKILL.md

@@ -3,22 +3,42 @@ name: sharepoint
 description: "Use when: building or debugging SharePoint list, library, file, or HTTP-request flows in a Power Apps Code App, including list-id or environment-variable-based setup."
 ---
 
-# SharePoint Connector Guide
+# SharePoint App Builder Guide
 
-> Agent limitation: do not use CLI commands directly from chat for SharePoint setup. Use the built-in Sync Connections and Deploy buttons instead.
+Use this skill when an app needs SharePoint list CRUD, file operations, library metadata, or a last-resort SharePoint HTTP request through `./connectors/sharepoint.js`.
 
-## Workflow
+Use the working OG-style SharePoint wrapper pattern from this repo as the reference: siteUrl-based connector paths, wrapper-side site URL encoding, `GetTables` lookup for the connector table token, and standard CRUD after resolution.
 
-Before writing code, prefer these connection approaches:
+Do not use CLI setup flows from chat. Use the built-in Auth, Sync Connections, and Deploy buttons.
+
+## First Questions To Ask
+
+Ask only the minimum needed to choose the right setup and write working code:
+
+1. Is this app working with a SharePoint list, files in a document library, or a custom SharePoint HTTP endpoint?
+2. What is the exact SharePoint site URL?
+3. Do you already have the SharePoint list ID?
+4. If not, do you at least know the list name for one-time resolution?
+5. Should config come from hardcoded app config or Dataverse environment variables?
+6. Does the current `power.config.json` already contain `connectionReferences.sharepointonline`?
+7. Which operations are required: read, create, update, delete, file create/move/delete, or custom request only?
+8. Are there complex SharePoint fields involved such as person, lookup, or multi-value choice columns?
+
+Preferred configuration order:
 
 - A: site URL + list ID
-- B: environment variables that resolve the site URL and list ID
+- B: environment variables that resolve site URL + list ID
+- C: site URL + list name only, resolved once through `resolveSharePointList(...)`
+
+Do not ask for a list name as the primary CRUD identifier. If the user only knows the list name, use it only as a lookup hint.
 
-Do not ask the user for a list name as the primary CRUD identifier. If they only know the list name, use `listTables(...)` once to discover the connector table ID and then continue with list-ID operations.
+Schemas are often stored in the 'agent' folder.
 
 ## power.config.json
 
-Expose `sharepointonline` in `connectionReferences`.
+Always read the current `power.config.json` before editing it.
+
+Ensure `"id": "/providers/Microsoft.PowerApps/apis/shared_sharepointonline"` exists and ` "dataSources": ["sharepointonline"]`.
 
 ```json
 {
@@ -33,45 +53,168 @@ Expose `sharepointonline` in `connectionReferences`.
 }
 ```
 
-No Dataverse tables are needed unless the app also uses environment variables.
-
-## Helper Surface
+Rules for editing `power.config.json`:
 
-The wrapper in `dev files/sharepoint.js` exports:
+- Preserve existing keys such as `sharedConnectionId`, `authenticationType`, and other working connection metadata.
+- No Dataverse tables are needed for basic SharePoint-only apps.
+- If the app uses Dataverse environment variables, also load the environment-variables skill and add the two Dataverse environment-variable tables there.
 
-- List ID pattern: `getItems`, `getSpItem`, `createSpItem`, `updateSpItem`, `deleteSpItem`
-- Generic helpers: `callSharePointOperation`, `sendHttpRequest`, `listTables`, `listLibrary`
-- File helpers: `createFile`, `updateFile`, `deleteFile`, `moveFile`, `getFileMetadata`
+## Core App Rules
 
-The list-ID helpers use the SharePoint connector table API. `sendHttpRequest(...)` remains available only as an advanced escape hatch when there is no dedicated helper for the operation you need.
+- Prefer dedicated SharePoint helpers over raw HTTP.
+- Keep SharePoint list discovery inside `sharepoint.js`, not in app pages or components.
+- Do not pre-encode the site URL. Pass the raw URL string and let the wrapper encode it.
+- If a list ID is known, still prefer resolving through `resolveSharePointList(...)` once at startup so the wrapper can match the connector table token.
+- If the app only knows a list name, use `resolveSharePointList(...)` or a by-list helper and let the wrapper do `listTables(...)` lookup.
 
-## Important Corrections
+When generating or fixing a local `dist/connectors/sharepoint.js` wrapper:
 
-- The single-item and CRUD helpers for the list-ID path are `getSpItem`, `createSpItem`, `updateSpItem`, and `deleteSpItem` in this repo.
-- `sharepoint.js` encodes `siteUrl` internally with `encodeURIComponent(...)`. Do not pre-encode the URL before passing it in.
-- For environment-variable based setup, import `getEnvironmentVariable(...)` from `./codeapp.js`, not from a separate `environmentVar.js` helper.
+- initialize the connector client with `getClient(dataSourcesInfo)`
+- keep the working SharePoint action parameter names aligned with the OG contract: `siteUrl`, `table`, `item`, and the standard CRUD/query names
+- keep reusable list-resolution helpers in the wrapper
+- preserve `callSharePointOperation(...)` as the escape hatch for supported actions
+- use `sendHttpRequest(...)` only when no dedicated helper exists
 
-## Example Imports
+## Recommended Startup Pattern
 
-Approach A:
+For list-backed apps, resolve the list once during startup and keep the returned access object in app state.
 
 ```js
-import { getItems, getSpItem, createSpItem, updateSpItem, deleteSpItem, listTables } from './sharepoint.js';
+import {
+  createSpItemByList,
+  deleteSpItemByList,
+  getItemsByList,
+  resolveSharePointList,
+  updateSpItemByList,
+} from './connectors/sharepoint.js';
+
+const oAppConfig = {
+  sSiteUrl: 'https://tenant.sharepoint.com/sites/example',
+  sListId: '00000000-0000-0000-0000-000000000000',
+  sListName: 'Tasks',
+};
+
+const oListAccess = await resolveSharePointList(oAppConfig.sSiteUrl, {
+  listId: oAppConfig.sListId,
+  listName: oAppConfig.sListName,
+});
+
+const aItems = await getItemsByList(oListAccess.sSiteUrl, oListAccess, { top: 200 });
+await createSpItemByList(oListAccess.sSiteUrl, oListAccess, { Title: 'New item' });
+await updateSpItemByList(oListAccess.sSiteUrl, oListAccess, 1, { Title: 'Updated item' });
+await deleteSpItemByList(oListAccess.sSiteUrl, oListAccess, 1);
 ```
 
-Approach B:
+Why this is the preferred pattern:
 
-```js
-import { getItems, getSpItem, createSpItem, updateSpItem, deleteSpItem } from './sharepoint.js';
-```
+- it keeps list lookup and fallback logic inside the wrapper
+- it works whether the connector resolves a table token or falls back to the configured list ID
+- it matches the working SharePoint demo app in this repo
+
+## Function Surface And Correct Usage
+
+Generic helpers:
+
+- `callSharePointOperation(operationName, parameters)`
+- `sendHttpRequest({ method, uri, headers, body })`
+- `listTables(siteUrl)`
+- `listLibrary(siteUrl)`
+- `resolveSharePointList(siteUrl, listReference)`
+
+List-ID CRUD helpers:
+
+- `getItems(siteUrl, listId, { filter, orderBy, top, skip })`
+- `getSpItem(siteUrl, listId, itemId)`
+- `createSpItem(siteUrl, listId, fields)`
+- `updateSpItem(siteUrl, listId, itemId, changedFields)`
+- `deleteSpItem(siteUrl, listId, itemId)`
+
+By-list CRUD helpers:
+
+- `getItemsByList(siteUrl, listReference, queryOptions)`
+- `getSpItemByList(siteUrl, listReference, itemId)`
+- `createSpItemByList(siteUrl, listReference, fields)`
+- `updateSpItemByList(siteUrl, listReference, itemId, changedFields)`
+- `deleteSpItemByList(siteUrl, listReference, itemId)`
+
+File helpers:
 
-Approach C:
+- `createFile(siteUrl, folderPath, fileName, fileContent)`
+- `updateFile(siteUrl, fileId, fileContent)`
+- `deleteFile(siteUrl, fileId)`
+- `moveFile(siteUrl, sourceFileId, destinationFolderPath, newFileName)`
+- `getFileMetadata(siteUrl, fileId)`
+
+Important behavior:
+
+- `resolveSharePointList(...)` returns both generic keys and app-friendly aliases: `siteUrl`, `listId`, `listName`, `sSiteUrl`, `sListId`, `sListName`, plus `table` and lookup metadata.
+- `getItemsByList(...)` and the other by-list helpers accept a list name, list ID object, or resolved access object.
+- Create and update payloads must be plain objects.
+- Item IDs can be strings or numbers.
+- Query options such as `top` and `skip` must be numeric if supplied.
+- `moveFile(...)` can rename during the move when `newFileName` is supplied.
+- `sendHttpRequest(...)` expects `{ method, uri, headers, body }` on the OG SharePoint wrapper contract.
+
+## Response Handling In App Code
+
+SharePoint item reads may come back as an array or inside a nested result shape. Normalize collections in app code before rendering tables or computing counts.
 
 ```js
-import { getEnvironmentVariable } from './codeapp.js';
-import { getItems, createSpItem, updateSpItem, deleteSpItem } from './sharepoint.js';
+function normalizeCollection(oPayload) {
+  if (Array.isArray(oPayload)) {
+    return oPayload;
+  }
+
+  const aCandidates = [
+    oPayload && oPayload.value,
+    oPayload && oPayload.items,
+    oPayload && oPayload.results,
+    oPayload && oPayload.body,
+    oPayload && oPayload.data,
+    oPayload && oPayload.result,
+    oPayload && oPayload.response,
+    oPayload && oPayload.d && oPayload.d.results,
+  ];
+
+  return aCandidates.find(Array.isArray) || [];
+}
 ```
 
-## Additional Build Nudge
+## Environment Variable Pattern
+
+If the app should not hardcode the site URL or list ID, load the environment-variables skill too.
+
+Rules:
+
+- Ask for the exact existing schema names.
+- Read values through `getEnvironmentVariable(...)` from `./codeapp.js`.
+- Update `power.config.json` with the Dataverse environment-variable tables only when the app actually uses them.
+- If a Data Source environment variable stores JSON, parse it before extracting the site URL or list ID.
+
+## Error Handling
+
+The wrapper already converts many connector failures into readable errors such as `SharePoint GetItems failed: ...`, so app code should display those messages rather than swallowing them.
+
+Keep separate loading and submit flags in UI state so refresh, create, update, and delete actions do not overlap silently.
+
+## Debugging Checklist
+
+- If the failure happens before any connector call, verify `initSharePointClient()` returns `getClient(dataSourcesInfo)` and the wrapper was not replaced with a stub.
+- If SharePoint calls suddenly return 404 after switching wrapper style, fall back to the OG siteUrl-based contract instead of a generated dataset or OData-style surface.
+- If you see `Provide a SharePoint listId or listName.`, the app never supplied startup list configuration.
+- If you see `SharePoint item payload must be an object.`, the app passed a string, `FormData`, or another invalid payload.
+- If you see `SharePoint site URL is required.`, the config source is empty or malformed.
+- If list resolution fails, confirm the site URL and list ID belong to the same site.
+- If the user only knows a list name, let the wrapper perform `listTables(...)` lookup instead of building lookup logic in the page.
+- Do not manually call `encodeURIComponent(siteUrl)` before passing the site URL to the wrapper.
+- Use `enableDebugger()` during app development so `_dbgWrap(...)` traces are available.
+- Use `sendHttpRequest(...)` only as an escape hatch when there is no dedicated SharePoint helper.
+
+## Summary Rules
 
-When a SharePoint build introduces or depends on specific lists and columns, create an `agent/listSchema.json` artifact so the user can recreate the list structure correctly.
+- Ask for site URL and list ID first.
+- Treat list name as a fallback lookup hint, not the primary identifier.
+- Update `power.config.json` by merging in `connectionReferences.sharepointonline`, not by overwriting working connection metadata.
+- Resolve the list once at startup and keep the resolved access object in app state.
+- Prefer by-list helpers in app code and keep list lookup inside `sharepoint.js`.
+- Show connector error messages directly in the UI.

package/AI/skills/start/SKILL.md

@@ -1,46 +1,54 @@
 ---
-name: frontend-design
-description: Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
+name: start
+aliases: start-codeapp
+description: Start skill for new project setup. Use this skill when starting a fresh app build or UI build so the agent confirms theme direction, offers mockups, and only then implements files.
 ---
 
-# Frontend Design Skill
+# Start: New Project Setup
 
-This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
+This skill applies only when the project is new (the decision log has no prior decisions). It ensures the agent gathers style and colour preferences and offers mockup creation before building.
 
-The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
+## folder setup
+The current folder should have a power-config.json file and a dist folder. If it does not the run the cap newApp command with a given name or one created by you.
 
-## Design Thinking
+## Style and Colour Direction
 
-Before coding, understand the context and commit to a BOLD aesthetic direction:
+Before building any creative UI (website, app, dashboard, landing page, etc.):
 
-- **Purpose:** What problem does this interface solve? Who uses it?
-- **Tone:** Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
-- **Constraints:** Technical requirements (framework, performance, accessibility).
-- For CAP code apps, treat workspace configuration and loaded skills as the source of truth for technical constraints. If `power.config.json` or the agent prompt already fixes the stack, connector, or app name, do not ask the user to restate them.
-- **Differentiation:** What makes this UNFORGETTABLE? What's the one thing someone will remember?
+1. Check if the user's message already includes colour, theme, or style direction.
+2. If style direction is **not** provided, ask: _"What colours or overall theme do you want for this site or app? If you do not want to choose, tell me to proceed and I will decide the visual direction myself."_.
+When interactive user input is available, ask through the interactive question flow and continue in the same session after the user answers.
+Only stop and wait for a later run when interactive user input is not available.
+3. If the user says to decide yourself, choose a bold and distinctive visual direction. Do **not** ask again.
+4. Record the chosen style and colour direction in `agent/decision-log.md` under **Custom Requirements**.
+5. Use the frontend-design skill when creating the UI, including for any mockups.
 
-**CRITICAL:** Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
+**Important:** The agent must have colour and style direction before building. Never start building a creative UI without it — either the user provides it or you decide it.
 
-Then implement working code in the project's required stack. Default to plain HTML/CSS/JS when the workspace instructions or agent prompt do not explicitly require a framework. Do not ask the user to choose React, Vue, or another framework unless the project requirements are genuinely ambiguous.
+## Mockup Offer
 
-- Production-grade and functional
-- Visually striking and memorable
-- Cohesive with a clear aesthetic point-of-view
-- Meticulously refined in every detail
+After style direction is established (or if the user's prompt already includes it):
 
-## Frontend Aesthetics Guidelines
+0. If a TODO checklist exists in `agent/decision-log.md`, ensure it includes these setup steps explicitly before any build tasks: theme/colour confirmation, mockup offer, optional mockup creation, then implementation.
+1. Check if mockup files already exist in the `agent/` folder. If they do, skip this step.
+2. If no mockups exist, ask: _"Do you want me to create 5 creative and unique mockups in agent/ for you to pick from? Reply yes or no."_.
+When interactive user input is available, ask through the interactive question flow and continue in the same session after the user answers.
+Only stop and wait for a later run when interactive user input is not available.
+3. If the user says yes, create 5 **CREATIVE** and **DISTINCT** HTML mockup options in `agent/`, using the frontend-design skill, then stop so the user can pick one. Name them clearly, for example `agent/mockup-1.html` through `agent/mockup-5.html`.
+Each mockup must be a self-contained, one-page HTML file that opens directly in a browser, shows the visual design, and includes lightweight interaction such as search filtering, panel toggles, or compose drawer open/close behavior. It is a visual prototype only, not a fully functional app.
+Create the files sequentially as you work: fully write `agent/mockup-1.html` before starting `agent/mockup-2.html`, and continue one mockup at a time instead of batching all file writes at the end.
+4. If the user says no or wants to skip, proceed directly to building in the same session.
+5. Never say a mockup is ready unless the corresponding files have actually been created in `agent/`.
 
-Focus on:
+## Interactive Sessions
 
-- **Typography:** Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
-- **Color & Theme:** Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
-- **Motion:** Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Only use framework-specific animation libraries when the project already uses that framework. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
-- **Spatial Composition:** Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
-- **Backgrounds & Visual Details:** Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
-NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
+- If the runtime says interactive user input is available, do not end the turn after a required clarification if the answer you need can be gathered through the interactive question flow.
+- After the user answers the required setup questions, continue with planning and implementation immediately.
+- Do not ask optional open-ended follow-up questions such as "let me know if you have more preferences" before producing the first concrete implementation unless the task is still blocked.
+- If the user asks how to view a mockup, point them to the actual generated files in `agent/`. Do not ask them to choose a framework when the project structure already dictates the implementation stack.
 
-Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
+## When to Skip
 
-IMPORTANT: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
-
-Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
+- If the user's prompt already contains style guidance **and** they explicitly decline mockups, proceed directly to building.
+- If the user's request is not a creative build (e.g. bug fix, add feature, deploy, refactor), skip this skill entirely.
+- If mockups already exist in the `agent/` folder, skip the mockup offer.