DEV Community: Olabode Lawal-Shittabey

Continuous AI Maturity Model: Where Do You Stand in the CAI Adoption?

Olabode Lawal-Shittabey — Mon, 22 Sep 2025 17:27:18 +0000

I was talking with Brian (@bdougieyo) and said I thought I was already at a higher level in the "Continuous AI maturity model".

I kinda bragged about it. But then I stopped to think harder. Am I really there?

That question is what led me to write this.

What is the Continuous AI Maturity Model?

The idea of maturity models isn’t new. Frameworks like the AI Maturity Model have long been used to describe how organizations grow in their use of artificial intelligence, moving from early experiments to full integration.

The first place I came across a Continuous AI Maturity Model was in @bekahhw’s article - A Developer's Guide to Continuous AI. She framed it as a way to understand how developers and teams build up their use of Continuous AI over time. It gives us a shared language for naming where we are today and spotting what the next step might be in the adoption of Continuous AI.

So what does this look like in practice? The model breaks down into levels, each with its strengths and limitations.

Level 1 — Manual AI assistance

This is where most developers are today. You copy some code or error into ChatGPT or another tool. You ask a question. You get back a function or a fix. It saves time.

The strength here is speed. You can solve problems faster. You can move past blockers. But the limit is clear too. You only get value when you remember to ask. The help is disconnected from your workflow. Nothing repeats itself.

Examples of level 1

Writing a test only when you ask the AI to write one
Asking for a regex when you can’t remember the pattern
Copying error logs into the AI to get a fix suggestion

Level 2 — Workflow automation

Here AI starts to live inside the work itself. It takes care of repeatable tasks while you still keep oversight. The workflow runs every time, not just when you think to ask.

The strength here is consistency. Everyone benefits from the same automation. The limit is trust. You still need to review and guide the AI. It can make mistakes.

Examples of level 2

AI adds missing documentation during a pull request review
AI suggests changes for style and small bugs directly in the PR
AI updates a ticket when a branch is merged
AI generates tests when new code is pushed

Level 3 — Zero intervention workflows

Here AI completes a process end to end with no human input. This is only safe today for narrow and low-risk workflows.

The strength here is scale. Work happens even when no one touches it. The limit is scope. You can’t trust AI to handle complex or high-risk work on its own.

Examples of level 3

AI merges dependency updates after tests pass
AI keeps a changelog updated without review
AI closes stale issues with a clear response

Why it matters

Not every developer or team is in the same place. Some are still mostly level 1. Others are testing level 2. Very few are ready for level 3. This model gives us a way to name where we are. It sets the tone for what we can aim at next without overpromising.

Moving up the levels

Moving from level 1 to level 3 in one leap is not realistic. Progression is what matters. Each step builds on what you’ve already learned.

Level 1 is where you get familiar with how your AI system behaves. You see its coding style when given your project context. You notice the way it writes documentation. You start to recognize patterns when you ask it to repeat the same tasks. At this stage, the key is learning how the AI works and where it fits.

Level 2 is when you take those patterns and set them into rules. Instead of reminding the AI every single time, you define the standards. You write down how you want code to be generated. You capture your preferred style for documentation. You build recipes that can run automatically or manually in place of those repeatable workflows.

A simple example from my own use: I have told my AI agent again and again to interact with GitHub through the CLI, not by trying to read the web page. When writing issues, pull requests, or comments, I ask it to create the content in a temporary markdown file and use the content as value for --body-file flag with the CLI, deleting the temporary markdown file after. This avoids bad inline formatting and keeps the output clean. Instead of repeating this instruction every time, I can set it once as a rule in the assistant’s configuration or in something like an AGENTS.md file, that's some new convention now.

All of this compounds in level 2. The more rules you set, the more the system adapts. If you’re using a tool like Continue that collects development data as you build, you get even more leverage. It starts to feel like the assistant is learning with you, while you also fine-tune it with your rules to match your taste.

Level 3 becomes possible only after enough usage at level 2. By then you can measure something important: the intervention rate. This is how often you still need to step in and fix the AI’s output. If the rate is high, you are not ready. But if over time the rate drops, because your rules are solid and the assistant is using project data well, then you have a system that can safely run end to end workflows without oversight.

The key is that level 3 is not magic. It only works because you built the foundation through repeated use, feedback, and rules at level 2.

Reflection

When I told Brian I was at level 2, maybe even 3 haha, I wanted to believe it. But the truth is I’m still mostly at level 1 with some bits of level 2 sprinkled in. I prompt the AI, I have a few rules, but I still clean things up often.

And that’s okay. The point isn’t to climb as fast as possible. It’s to know where you are, notice your improvements, and keep building. Each level builds on the one before. The more you use AI with care, the more you prepare it — and yourself — for higher levels of maturity.

The Continuous AI Maturity Model isn’t about chasing some end state. It’s about knowing where you stand, what’s working for you, and what step makes sense next.

Why Continuous AI Matters for Developers and Teams

Olabode Lawal-Shittabey — Thu, 11 Sep 2025 17:07:50 +0000

“Will AI replace developers?”, it's a debate we've all heard and It’s old-tuned by now. But the sharper take is this: “Developers who learn to harness AI will replace the ones who don’t”. The future isn’t about competing with AI but collaborating with it; and the clearest way that’s happening today is through Continuous AI.

Picture this: You’re deep in flow, building out a new feature. The code is coming together nicely, but haha you know what’s waiting for you; tests to write, docs to update, and a PR review cycle that might drag out for days. You sigh, because while these steps are necessary, they also pull you out of the creative momentum you’re in.

Now imagine instead that while you code, an AI agent is already generating the unit tests, updating the README, and lining up a polished PR draft; all without you leaving your editor. By the time you’re done, your work isn’t just complete, it’s complete with everything.

That’s the kind of shift Continuous AI (CAI) brings.

Gains For Indie Developers: Becoming Amplified

For individual developers, Continuous AI feels less like a tool, and more like a collaborator in your workflow. It takes care of the repetitive and predictable tasks, leaving you free to focus on solving harder problems and exploring creative solutions while you grab something to eat ;). You move faster, with less context-switching, and with a safety net that catches the details you might otherwise miss.

This idea closely ties into what’s described at amplified.dev; the vision of transforming everyday developers into Amplified Developers: professionals who don’t just write code, but orchestrate AI-powered workflows to multiply their impact. It’s a future where your productivity isn’t limited by how much you can type in a day, but by how well you design and guide these amplified systems.

I personally endorse this vision and encourage you to check it out. If it resonates with you, consider joining the supporters by adding your name to the growing community of developers shaping what it means to be amplified.

Gains For Teams: Shared Intelligence at Scale

For teams, Continuous AI doesn’t just boost individual productivity, it completely transforms collaboration. Imagine every teammate having access to the same AI-augmented workflows: consistent PR/code reviews, standardized test generation, and shared prompts that ensure everyone is on the same page. Instead of fragmented one-off uses, the whole team benefits from a unified intelligence layer built into the project.

This is already happening in two key ways:

Inside the editor (local dev environments): Tools like Continue give teams a consistent CAI experience directly in their IDEs. Teams can define custom agents with project-specific rules, shared prompts, and ensure everyone benefits from the same context-aware AI workflows. This keeps collaboration tight and reduces knowledge silos.
In the pipeline (infrastructure + actions): GitHub is experimenting with AI-inference Actions by coupling GitHub Actions with GitHub Models and the prototype GitHub Agentic Workflows. This powers things like automated PR reviews, continuous documentation, intelligent issue triage, dependency updates and even more complex flows. The AI becomes part of the team’s CI/CD backbone, continuously working in the background to reduce manual overhead.

The result? Teams spend less time coordinating and more time building.

The Real Gain: Flow

The biggest win isn’t just productivity; it’s flow.

Flow is when you’re immersed in the work, ideas connect easily, and collaboration feels natural. Continuous AI removes the stop-start friction of coding, testing, documenting, and reviewing. It gives developers space for creativity, confidence, and joy in their craft.

Getting Started with Continuous AI

This isn’t a far-off vision, it’s already here. For indie developers, tools like GenAIScript lets you write workflows and run them locally or on GitHub Actions. Tools like Continue work great for individuals and teams alike, embedding CAI directly into your editor. Larger teams can also look to GitHub’s AI-powered Actions and Models to bring intelligent automation into their CI pipelines.

If you’re not sure where to begin, the Awesome Continuous AI repo is a great place to discover tools, frameworks, and experiments that push the space forward. And if this idea of Continuous AI feels new, you might want to check out my first post — Continuous AI: A Simple Introduction — for the basics before diving deeper.

Pro tip: Start small, automate one repetitive task and let your Continuous AI journey grow from there.

Continuous AI: A Simple Introduction

Olabode Lawal-Shittabey — Tue, 26 Aug 2025 12:37:32 +0000

When Continuous Integration and Continuous Delivery (CI/CD) first emerged, it completely transformed how teams ship software. Software releases became predictable, automated, and reliable. CI/CD didn’t just add speed; it changed the way developers thought about building and shipping altogether.

We’re now at a similar turning point with AI in software development. Instead of treating AI tools as something we copy-paste into when we get stuck, we can start thinking of them as part of the continuous developer workflow, embedded directly in our editors, always aware of our context, and ready to automate repetitive tasks. This is the promise of Continuous AI (ContinuousAI).

What is Continuous AI?

The term Continuous AI was first introduced by the GitHub Next team to describe a shift in how AI fits into the developer workflow. To understand it, let’s first look at how most developers use AI today:

You copy a snippet of code, paste it into ChatGPT (or another AI tool), ask it for help, then copy the result back into your editor. It’s useful, but it’s fragmented; disconnected from the actual flow and context of development.

Now compare that to CI/CD (Continuous Integration and Continuous Delivery). CI/CD brought automation directly into the pipeline. Every commit triggers tests, builds, and deployments automatically. Developers don’t need to leave their workflow; it’s baked into the process.

Continuous AI (ContinuousAI) applies that same mindset to AI. Instead of being an occasional side tool, AI becomes a continuous part of your development loop, integrated into your editor, aware of your project context, and able to run repeatable, sharable workflows.

At its core, Continuous AI rests on four principles:

Context Awareness – AI doesn’t just see isolated snippets; it understands your codebase, diffs, terminal outputs, configuration and documentations to mention a few.
Seamless Integration – No more copy-pasting between tools; the AI lives where you work, inside your IDE or development Pipeline.
Repeatable Workflows – Like CI pipelines, you can define reusable “recipes” (e.g., write tests for this diff, generate docs, fix errors, review pull requests), ensuring tasks are consistent and reproducible.
Extensibility – You can plug in different AI models and customize rules, context providers, and prompts to fit your workflow, just like extending a CI/CD pipeline.

Continuous AI is about amplification. Just as CI/CD automated the mechanics of shipping code, Continuous AI extends that automation with intelligence. It makes AI a collaborator in the workflow, spotting issues earlier, suggesting improvements in real time, and helping teams move faster with confidence. Developers stay in the driver’s seat, now supported by a co-pilot that evolves with the project.

Examples of Continuous AI in Action

Continuous AI isn't just about one-off prompts, it’s about creating workflows that consistently run intelligent automation. Here are some great real-world use cases:

Smarter Code Reviews - Instead of manually catching small issues or style inconsistencies, AI agents can review pull requests in real-time, flagging bugs, suggesting improvements, or even generating patches. Tools like CodeRabbit and GitHub Copilot Code Review are already doing this by embedding into GitHub workflows to keep quality checks continuous.
End-to-End Task Automation - AI agents can take on multi-step workflows like fixing a bug, running tests, updating related documentation, and opening a PR with little to no human-oversight. Frameworks like Continue and GitHub Copilot Agent show how this continuous, agentic approach reduces repetitive coordination and keeps developers focused on creative problem-solving.
Continuous Documentation - Documentation doesn’t have to lag behind code. AI can keep READMEs, API references, and changelogs in sync with the codebase, reducing the common “stale docs” problem.
Context-Aware Test Generation - Instead of manually writing tests for each new feature, AI can generate them on the fly, adapting as code evolves.

These workflows elevate AI from “help me write this one time” to “help me automatically every time” by making outputs context-aware (i.e. understanding the code, files, to even issues in your repository) while also being integrated directly into pipelines so they trigger on commits, or pull requests, and ensuring they remain consistent and shareable so every developer on the team benefits from the same automation.

Here so...

Continuous AI moves you from those one-off AI interactions to a rhythm where AI actively supports your work, day in and day out. Instead of treating it like a quick helper, you integrate it as part your flow, handling repetitive or structured tasks with consistency. This shifts your attention from the busywork to the parts of the job that need real human creativity and decision-making.

How to Get Started with Continuous AI Tools

The best way to understand Continuous AI is to try it out. Many tools are already available to developers, from lightweight assistants that help you debug code as you write, to more advanced frameworks that can automate repetitive workflows. Exploring these tools doesn’t require overhauling your entire setup; start small, experiment with one that aligns with your daily tasks, and see how it changes the way you work.

A great place to start is the Awesome Continuous AI repo, which curates a wide collection of Continuous AI tools and frameworks you can experiment with. Pick one, play around, and start carving your own path into Continuous AI.

Building jargons.dev [#7]: The Word Editor Script

Olabode Lawal-Shittabey — Fri, 06 Dec 2024 13:43:26 +0000

Remember the "The Word Editor"!? Here's the script responsible that implements it's end-to-end functionalities that allows for writing changes via the user interface to a user's forked repository.

The Functional Breakdown

The Word Editor empowered by the script should perform two (2) functions, taking some certain steps

Write New Word - basically to add new word to the dictionary; does this in the following steps...
- Get an already established word template (.md) file
- Fill template placeholder with collected word title and content to create a word.mdx file in the appropriate words directory src/pages/browse
- and commit the change to an established change branch/ref on the user's forked repository
Edit/Update Existing Words - modify existing word in the dictionary, it does this in the following steps...
- Get an existing word from the user's fork of jargons.dev (looking in the words directory src/pages/browse)
- Parse its content and make necessary edits
- and and commit the change to an established change branch/ref on the user's forked repository

The breakdown inspired creation of the following helper and utility functions.

writeNewWord - a function that accepts the word title and content amongst others, leveraging the user's GitHub authenticated instance, it perform a write operation i.e. writing a new file (word.mdx) to a fork of jargons.dev on the user's account on their behalf through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint.
getExistingWord - a function that simply retrieves the content of an existing word file on the user's forked repository, with the aim of availing it for edit. It does this by taking the word as argument and concatenates it in the path param (example src/pages/browse/${normalizeAsUrl(word)}.mdx) of the request it makes to the endpoint "GET /repos/{owner}/{repo}/contents/{path}"; It is important to state that I had to make a few adjustments to the returned data from this helper for consumption reason, the adjustments are as followed
- Added title property: the response.data object which comes from the query to the endpoint "GET /repos/{owner}/{repo}/contents/{path}" doesn't have a title property (this is the word itself);
- Added content_decoded property: the response.data.content property holds the main content of the retrieved word, BUT it comes in a "base64" format; so I thought it'd be nice if the functional avails it in the consumption-ready format which can be use immediately without the need to convert at consumption. These I did with code below...
```
const { content, ...responseData } = response.data;

return {
  title: word,
  content,
  content_decoded: Buffer.from(content, "base64").toString("utf-8"),
  ...responseData
};
```
updateExistingWord - with an initial name of editExistingWord and changed to current name in jargonsdev/jargons.dev#34, this function performs similar operation with the writeNewWord but it over-writes existing word content in a specific file by replacing the file with another file with updated content. This is also done via user's account on their behalf through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint.
writeFileContent - this helper as implied in its name does one thing — it writes file content for words which is submitted in requests made by both writeNewWord and updateExistingWord to the GitHub API, it does this by taking a word title and content (i.e. word definition) as variable and generates a content from a template avail to it replacing placeholder contents in it.

The PR

feat: implement `word-editor` script #18

babblebey posted on Apr 02, 2024

This Pull request implement the word-editor script; the primary functionality of this script is to allowing adding new word, retrieve and update existing word which are individual .mdx files residing in the src/pages/browse directory of the project. This script avails us of all the helper functions required to perform this operations.

Changes Made

Implemented the writeNewWord function - this function takes 3 params namely the userOctokit, forkedRepoDetails, and the word; it leverages the userOctokit instance to perform a write operation i.e. writing a new file (newWord.mdx) to a fork of our project on the user's account on behalf of the user through the "PUT /repos/{owner}/{repo}/contents/{path}" endpoint
Impelemented the getExistingWord function - this function helps retrieve data of existing words in the fork of our project on the user's account by calling the "GET /repos/{owner}/{repo}/contents/{path}" endpoint; it returns an object which carries the following properties that we are mostly interested in...
- title - title of the the existing word - this infact is a custom appended data to the response.data from the call made to the endpoint
- path - path to the existing word file
- sha - unique SHA of the existing word
Implemented the editExistingWord function - this function takes 3 params namely the userOctokit, forkedRepoDetails, and the word (holds the properties: path, sha, title and content); it leverages the userOctokit instance to perform a edit operation i.e. updating the existing file on a fork of our project on the user's account on behalf of the user through thesame "PUT /repos/{owner}/{repo}/contents/{path}" endpoint
Implemented writeFileContent helper function - this function help write a content for our dictionary word file generating them from another added constant in the src/lib/template/word.md.js

Screencast/Screenshot

too lazy to record a screencast for this one 😜, but trust me 🤞 the shit works 😮‍💨

View on GitHub

Building jargons.dev [#6]: The Branch Script

Olabode Lawal-Shittabey — Tue, 19 Nov 2024 14:23:27 +0000

This should be really short haha 😃, considering the branch script is the smallest of them (The Scripts) all.

The Branch Script's primary assignment is to hold all helper functions that can be used to perform operation related to References (aka Branch) on the GitHub APIs.

The Script

Noting the primary responsibility of the branch script which is
to create a reference/branch of repo (in this case would be the jargons.dev repo fork) on an authenticated user's account. I got to work quickly by doing the following...

Implemented the main createBranch function in the branch script which accepts necessary param to perform the following operation in the stated order...
- It initially fetches the forked repository main branch where we wished to create the new branch off of; it does this using the getBranch helper (a function that was created in the fork script); this return the SHA of the branch
- Then makes a POST request to the endpoint "/repos/{owner}/{repo}/git/refs" to create the new branch; passing in the full name of the user's fork, the head branch SHA and the name of the new branch we wish to create.
I also took the initiative of moving the getBranch helper function from the fork script to a the branch script — feels more like home 😉.

The PR

feat: implement `branch` creation script #17

babblebey posted on Apr 01, 2024

This Pull request implements the branch creation script whose primary function is to create a new branch from the forked repository for an authenticated user.

Changes Made

Implemented the main createBranch function in the branch script at src/lib/branch.js; this function takes in 3 params;
- userOctokit - a user authenticated instance of octokit that can be used to perform action on user's behalf
- repoDetails - the user's forked repo details; hold the repoFullname and repoMainBranchRef as properties in the object type param
- newBranchName - name of the branch that will be created for the user
The createBranch function performs the following operation in the stated order...
- It initially fetches the forked repository main branch where we wished to create the new branch off of; it does this using the getBranch helper function; this return the SHA of the branch
- Then we make a request to the endpoint "POST /repos/{owner}/{repo}/git/refs" to create the new branch; passing in the repoDetails.repoFullname properties, the head branch SHA and the newBranchName.
Moved the getBranch function from the fork script to the branch script

Screencast/Screenshot

screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.04.01-13_54_14.webm

View on GitHub

Building jargons.dev [#5]: The Fork Script

Olabode Lawal-Shittabey — Mon, 09 Sep 2024 11:09:20 +0000

This is the first of 4 scripts I set out to write as stated in the system architecture. Felt pumped! it was a step in the direction of creating the "wiki" experience that gets a contribution to Open source without interfacing with the GitHub UI 😁.

What are these scripts?

These are js files that holds some related helper functions particularly meant to be used to interact with the GitHub APIs; they are either consumed within the same script or exported to be used to perform their base functionality elsewhere within the project. They accept an authenticated Octokit instance of a user as params out of others, this instance is used to perform actions/functions through the GitHub APIs on behalf of the authenticated user.

The need to create a flow of contributing to Open source without interfacing with the GitHub UI meant that we had to automate some process - simulating every steps a user will take if they were to contribute via the GitHub UI, the steps are as follows..

Fork Project Repo
Create a Branch
Commit Changes to the Branch (add new mdx file in src/pages/word/ directory for new word or edit existing ones, in our case)
Create a Pull Request (Submit the word changes, in our case)

A Truth worth stating

I started writing this script right after the initial commit, this was infact the PR #2, but it took a hit during the long month break 🫣 i took from the project before getting back to work on the base dictionary feature.

The Script

The task here was to create "The Fork Script" — whose end goal is to create/get a fork of the jargons.dev repo on/from a user's account. It should house every function that'll do the following.

Check whether a Fork of jargons.dev already exists on a user's account
- If Fork Exists
  - Check if the Fork is in-Sync with upstream (i.e. up-to-date with jargons.dev repo main branch); IF NOT — Update the fork
- If NO Fork is found
  - Create the Fork

Understanding the assignment, I "delved" straight into working on the script.

I already I'm very used to the GitHub APIs due to my frequent consumption in my everyday work on Hearts ❤️... So I had the GitHub's Fork Documentation looking like a broski to me 😌...

The Steps

I created a main forkRepository function which was the main entry point to executing the fork functionality - it leads everywhere else
I added the following functions, which mostly served as helper to the obvious main forkRepository function
- isRepositoryForked - this function checks whether the jargons.dev repository is already forked to the current authencated user's account
- isRepositoryForkUpdated - to check whether the fork (if found) is (in Sync with head repo) up-to-date with main jargons.dev repo
- updateRepositoryFork - used to update (Sync) repository to state of main (head) jargons.dev repository
- getBranch - is a base utility (required at the point of writing this script) used to fetch Branch/Ref details for the jargons.dev repo and user's fork to use in the comparison that is done in the isRepositoryForkUpdated helper to perform its primary function; it uses the the GitHub References endpoint.

My weird assumption

Running through my mind 🤔 as I wrote this script was a thought that I held onto after reading the below quoted paragraph on the GitHub Fork Documentation

Note: Forking a Repository happens asynchronously. You may have to wait a short period of time before you can access the git objects. If this takes longer than 5 minutes, be sure to contact GitHub Support.

I misunderstood this and assumed that we were only going to be able to initiate a fork process, move on and surely not gonna be able to wait for a response object that returns the details of the new fork because we don't know when the fork process completes.

This assumption forced me to not return any data from the main forkRepositoryfunction and I was already starting to think at this point - how am I gonna get the fork details to process to the next phase of the contribution process!? Hmm, maybe I'll use webhooks 🤔!?

It turned out I was overthinking it 😂, I realised later that I will infact get a response details for the fork and this led me to do a follow up PR to address returning the data required from the fork response object for consumption in the contribution process.

The PR

Main:

feat: implement `fork` repository script #3

babblebey posted on Dec 31, 2023

This Pull Request implements the fork script; this script is intended to be used to programmatically fork the main project repo to a user account; It houses a main function and other helper functions it uses to perform some necessary actions in order to ensure an efficient repo fork operation.

Changes Made

Implemented the main forkRepository function within script; this function is the main exported function that performs the main fork operation; it accepts a userOctokit (a user authenticated object with permission to act on behalf of the user) instance and the project's repository details i.e. repoDetails object and it does the following...
- It checks whether the project repository has already been forked to the user's account using the isRepositoryForked helper function; this returns the fork of null
  - If the repo has already been forked, then we perform a check whether the fork is up-to-date/in sync with main project repo using the isRepositoryForkUpdated helper function; this returns the updatedSHA and a boolean isUpdated property that confirm whether fork is up-to-date
    - If fork is not up-to-date; then we perform the update by bringing it in sync with the main project repo using the updateRepositoryFork helper function
  - If repo is up-to-date/in sync with main project repo; we cancel out of the operation at this point with an early return;
- If the project repository is not forked onto the user's account; then we proceed to initiating a fork process by calling the "POST /repos/{owner}/{repo}/forks" endpoint using the userOctokit instance. (This starts the fork process, we do not know exactly when the process completes 🤔)
Implement the following helper functions consumed within the main forkRepository function and within other helper functions too
- updateRepositoryFork - used to update (Sync) repository to state of main (head) repository
- isRepositoryForkUpdated - used to check whether a fork is (in Sync with head repo) up-to-date with main repo
- getBranch - used to fetch a Branch/Ref details
- isRepositoryForked - used to check for the presence of a specific repo in a user's fork repo list
Added getRepoParts to /lib/utils; its a utility function that is used to resolve repoOwner and repoName from a repository fullname.

Related Issue

Resolves #2

Screencast/Screenshot

https://github.com/babblebey/jargons.dev/assets/25631971/16221b7e-3c28-4c6c-a1f3-24d583ce7e3a

📖

View on GitHub

Follow-up:

feat: return repo `fullname` in fork script #29

babblebey posted on Apr 04, 2024

This PR is a follow-up to a missing step in the fork script initial implementation at #3; the fork script failed to return a repo which can be used to in the next step of computation. This was because of a weird assumption I had during the initial implementation. 😆See my assumption below...

I assume that the call to the "POST /repos/{owner}/{repo}/forks" endpoint only assures of initiating a fork process without assuring us of a response at all. Meaning we might not exactly get a response.data following the call

...but that wasn't true, I found out that a response.data actually comes, but it might just take some time and only in cases where the repo being forked is huge.... and at the moment forking the project repo happens in less than 5secs.

Changes Made

Returned fork repo - this is a repo fullname value returned from the isRepositoryForked helper function; I hereby return it as main returned value from the forkRepository function execution in the condition where the repo is already forked on a executing user's account
Returned response.data.full_name - this is a newly created fork repo fullname; Its a value from the response to the "POST /repos/{owner}/{repo}/forks" endpoint call; I hereby return it as main retuned value from the forkRepository function execution in cases where there was no fork already already found on the executing user's account
Cherry picked some changes from #25 to use on here
- f12f25f548a5c5836e9be7d601ed226c5269f5ee
- 436ceea649b67812c0ec1164fde95d443ce556e0

📖

View on GitHub

Building jargons.dev [#4]: The Authentication System

Olabode Lawal-Shittabey — Mon, 26 Aug 2024 15:42:56 +0000

As a developer, Authentication is one of the things that I've got the most respect for; In my experience doing authentication (maybe on a basic level), I've always struggled with one thing or the other especially when I've got to integrate OAuth.

Prior to working on this for jargons.dev, my most recent experience doing Auth was on Hearts where I integrated GitHub OAuth.

// Detect dark theme var iframe = document.getElementById('tweet-1735788008085856746-253'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1735788008085856746&theme=dark" }

So yea! I also had my (traditional 😂) struggles working on this for jargons.dev too; but honestly this was only because of the differences in setup (i.e. technology) though — My experience on Hearts was integrating GitHub OAuth with Server Actions in NextJS meanwhile on jargons.dev, I'm integrating GitHub OAuth with Astro.

The Iterations

As I currently write, the authentication system has gone through 3 Iterations, with more planned (details on next iteration in this issue #30); these iterations over the weeks of development have implemented improvements or refactored a thing or two due to some uncovered limitation.

First Iteration

This iteration implemented in base authentication functionality that allows initiation of a GitHub OAuth flow, response handling that exchanges the authentication code for an accessToken that we securely store on user's cookies.

The imperative changes worth stating about this iteration is that

I integrated a GitHub App OAuth wich uses permissions with its fine-grained token offering; this promises a short-lived accessToken with a refreshToken.
I implemented 2 API route for handling the Auth related requests
- api/github/oauth/callback - which handles the response from the OAuth flow by redirecting to a specific path the request was made from with the flow authorization code
- api/github/oauth/authorize- a route called from the redirect path, served with the flow authorization code, exchanges the code for access token and returns it as response.
I implemented the first action (not related to the new and experimental Astro Server Actions, I done this long before the announcement 😏) — this is a term I just made up to call functions that are ran on the server-side of Astro "before the page loads", you shall know it by its naming convension: doAction, and its style of taking the astroGlobal object as the only parameter, it's usually async function that returns a response object.
- doAuth - this action integrates on any page I wish to protect, it checks for the presence of an access token in cookie; — if present: it exchanges that for user data, returns a boolean value isAuthed alongside it to confirm authentication for protected page; — if no token is found: it checks the presence of the oath flow authorization code in url search params, exchanges that for access token (by calling the api/github/oauth/authorize route) and saves it secure to cookies, then uses the cookie appropriately; now in cases where no accessToken is found in cookies and no auth code is in url search params, then the returned value isAuthed is false and it will be used on the protected page to redirect to the login page.
```
const { isAuthed, authedData: userData } = await doAuth(Astro);
if (!isAuthed) return redirect(`/login?return_to=${pathname}`);
```
- ...this doAuth action also returns a utility function getAuthUrl that is used to generate a GitHub OAuth flow url which is in turn added as link to the "Connect with GitHub" on the login page and once clicked, it starts an OAuth flow

// Detect dark theme var iframe = document.getElementById('tweet-1773811079145009311-351'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1773811079145009311&theme=dark" }

See PR:

feat: implement auth (with github oauth) #8

babblebey posted on Mar 29, 2024

This Pull request implement the authentication feature in the project; using the github oauth, our primary goal is to get and hold users github accessToken in cookies for performing specific functionality. It is important to state that this feature does not take store this user's accessToken to any remote server, this token and any other information that was retrieved using the token are all saved securely on the users' end through usage of cookies.

Changes Made

Implemented the github oauth callback handler at /api/github/oauth/callback - this handler's main functionality is to receive github's authorization code and state to perform either of the following operations
- Redirect to the path stated in the state params with the authorization code concatenated to it using the Astro.context.redirect method
- or If a redirect=true value if found in the state param, then we redirect to the the path stated in the state params with the authorization code and redirect=true value concatenated to it using Astro.context.redirect method
Implemented the github oauth authorization handler at /api/github/oauth/authorization - this handler is a helper that primarily exchanges the authorization code for tokens and returns it in a json object.
Created a singleton instance of our github app at lib/octokit/app
Added a new crypto util function which provides encrypt and decrypt helper function has exports; it is intended to be used for securing the users related cookies

Implemented the doAuth action function - this function take the Astro global object as argument and performs the operations stated below

/**
 * Authentication action with GitHub OAuth
 * @param {import("astro").AstroGlobal} astroGlobal 
 */
export default async function doAuth(astroGlobal) {
  const { url: { searchParams }, cookies } = astroGlobal;
  const code = searchParams.get("code");
  const accessToken = cookies.get("jargons.dev:token", {
    decode: value => decrypt(value)
  });

  /**
   * Generate OAuth Url to start authorization flow
   * @todo make the `parsedState` data more predictable (order by path, redirect)
   * @todo improvement: store `state` in cookie for later retrieval in `github/oauth/callback` handler for cleaner url
   * @param {{ path?: string, redirect?: boolean }} state 
   */
  function getAuthUrl(state) {
    const parsedState = String(Object.keys(state).map(key => key + ":" + state[key]).join("|"));
    const { url } = app.oauth.getWebFlowAuthorizationUrl({
      state: parsedState
    });
    return url;
  }

  try {
    if (!accessToken && code) {
      const response = await GET(astroGlobal);
      const responseData = await response.json();
  
      if (responseData.accessToken && responseData.refreshToken) {
        cookies.set("jargons.dev:token", responseData.accessToken, {
          expires: resolveCookieExpiryDate(responseData.expiresIn),
          encode: value => encrypt(value)
        });
        cookies.set("jargons.dev:refresh-token", responseData.refreshToken, {
          expires: resolveCookieExpiryDate(responseData.refreshTokenExpiresIn),
          encode: value => encrypt(value)
        });
      }
    }
  
    const userOctokit = await app.oauth.getUserOctokit({ token: accessToken.value });
    const { data } = await userOctokit.request("GET /user");
  
    return {
      getAuthUrl,
      isAuthed: true,
      authedData: data
    }
  } catch (error) {
    return {
      getAuthUrl,
      isAuthed: false,
      authedData: null
    }
  }
}

it provides (in its returned object) a helper function that can be used to generate a new github oauth url, this helper consumes our github app instance and it accepts a state object with path and redirectproperty to build out thestate` value that is held within the oauth url
it sets cookies data for tokens - it does this when it detects the presence of the authorization code in the Astro.url.searchParams and reads the absense no project related accessToken in cookie; this assumes that there's a new oauth flow going through it; It performs this operation by first calling the github oauth authorization handler at /api/github/oauth/authorization where it gets the tokens data that it adds to cookie and ensure its securely store by running the encrypt helper to encode it value
In cases where there's no authorization code in the Astro.url.searchParams and finds a project related token in cookie, It fetches users's data and provides it in its returned object for consumptions; it does this by getting the users octokit instance from our github app instance using the getUserOctokit method and the user's neccesasry tokens present in cookie; this users octokit instance is then used to request for user's data which is in turn returned
It also returns a boolean isAuthed property that can be used to determine whether a user is authenticated; this property is a statically computed property that only always returns turn when all operation reaches final execution point in the try block of the doAuth action function and it returns false when an error occurs anywhere in the operation to trigger the catch block of the doAuth action function

Added the login page which stands as place where where unauthorised users witll be redirected to; this page integrates the doAuth action, destruing out the getAuthUrl helper and the isAuthed property, it uses them as follows
```
const { getAuthUrl, isAuthed } = await doAuth(Astro);

if (isAuthed) return redirect(searchParams.get("redirect"));

const authUrl = getAuthUrl({
  path: searchParams.get("redirect"),
  redirect: true
});
```
- isAuthed - this property is check on the server-side on the page to check if a user is already authenticated from within the doAuth and redirects to the value stated the page's Astro.url.searchParams.get("redirect")
- When a user is not authenticated, it uses the getAuthUrl to generate a new github oauth url and imperatively set the argument state.redirect to true
- Implemented a new user store with a Map store value $userData to store user data to state

Integration Demo: Protect `/sandbox` page

// pages/sandbox.astro

---
import BaseLayout from "../layouts/base.astro";
import doAuth from "../lib/actions/do-auth.js";
import { $userData } from "../stores/user.js";

const { url: { pathname }, redirect } = Astro;
const { isAuthed, authedData } = await doAuth(Astro);

if (!isAuthed) return redirect(`/login?redirect=${pathname}`);

$userData.set(authedData);
---

<BaseLayout pageTitle="Dictionary">
  <main class="flex flex-col max-w-screen-lg p-5 justify-center mx-auto min-h-screen">
    <div class="w-fit p-4 ring-2 rounded-full ring-gray-500 m-auto flex items-center space-x-3">
      <img class="w-10 h-10 p-1 rounded-full ring-2 ring-gray-500" 
        src={authedData.avatar_url} 
        alt={authedData.login}
      >
      <p>Hello, { authedData.login }</p>      
    </div>
  </main>
</BaseLayout>

Explainer

We destructure isAuthed and authedData from the doAuth action
Check whether a user is not authenticated? and do a redirect to login page stating the current pathname as value for the redirect search param (a data used in state to dictate where to redirect to after authentication complete) if no user is authenticated
or Proceed to consuming the authedData which will be available when a isAuthed is true. by setting it to the $userData map store property

Screencast/Screenshot

screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.03.29-20_36_15.webm

Note

Added new node package https://www.npmjs.com/package/@astrojs/node for SSR adapter intergation

View on GitHub

Second Iteration

This iteration implements improvements by making making the parsedState derived from the getAuthUrl function call more predictable removing the chances of an error in the api/github/oauth/callback route; it also renames some terms used in the search params and implements the the encodeURIComponent to make our redirect urls look less weird

See PR:

feat: implement `auth` (second iteration) improvements #28

babblebey posted on Apr 04, 2024

This PR implements some improvement to mark the second iteration of the auth feature in the project. Follow-up to #8

Changes Made

Addressed "todo make the parsedState data more predictable (order by path, redirect)" by implementing more predicatable manner of generating the state string for the oauth url; this is done by individually looking for the required state object key to fill in the parsedState string in required order. Leaving the new getAuthUrl helper function looking like so...

function getAuthUrl(state) {
  let parsedState = "";

  if (!isObjectEmpty(state)){
    if (state.path) parsedState += `path:${state.path}`;
    const otherStates = String(Object.keys(state)
      .filter(key => key !== "path" && key !== "redirect")
      .map(key => key + ":" + state[key]).join("|"));
    if (otherStates.length > 0) parsedState += `|${otherStates}`;
  }

  const { url } = app.oauth.getWebFlowAuthorizationUrl({
    state: parsedState
  });

  return url;
}

Implemented a new utility function isObjectEmpty to check if an object has value or not
Removed usage of redirect property in state object; its redundant 😮‍💨
Renamed login redirect path params property name to return_to from redirect for readability reasons
Implemented encodeURIComponent in login redirect path params value to stop its part on the url from looking like weird 😃;
- Takes the example url from looking like this... /login?return_to=/editor to looking like so... /login?return_to=%2Feditor

Related Isssue

Resolves #15

View on GitHub

Third Iteration

This iteration refactors the most parts of the implementation in the "First Iteration" because of a certain limitation that surfaced during the work I was doing on another script.

At this point in time I was working on the "Submit Word" script; this script leverages the GitHub API and create a Pull Request to merge changes made from the currently authenticated user's fork branch to the base (jargons.dev) main branch. This ofcourse is made possible by the access token of the user saved to cookies which is used in the request headers as "Authorization Bearer token" by the SDK i.e. Octokit that facilitates our interaction with the GitHub APIs.

The Limitation

During a test moment as I gave the submit word script a whirl, I was met by the error...

Error: Resource not accessible by integration

...this quickly became a blocker and I consulted @gr2m with whom we quickly uncovered the limitation which related to my integrations of GitHub App.

As initially stated, the GitHub App uses "Permissions" with a fine-grained token - a new token type that GitHub encourages for some very good reasons with the below quoted one as one that concerns us here...

GitHub Apps provide more control over what the app can do. Instead of the broad scopes that OAuth apps use, GitHub Apps use fine-grained permissions. For example, if your app needs to read the contents of a repository, an OAuth app would require the repo scope, which would also let the app edit the repository contents and settings. A GitHub App can request read-only access to repository contents, which will not let the app take more privileged actions like editing the repository contents or settings.

...this means that when using "Permissions" (i.e. fine-grained permissions), a user must have write access to the upstream/base repository which in this case is our jargons.dev repository; as stated in the GitHub Create a Pull Request docs.

Say what!? Nope!!!

It was at that point that we found plain old scope to be exactly what we need; In order to be able to access the required resource, the public_repo scope was everything.

The Swap for GitHub's OAuth App from GitHub App

In order to move forward, I had to switch from "permissions" to "scope" and where we found that was in the GitHub's "OAuth App"; this was the basis on which the third iteration was patched.

So this iteration mainly focused on exchanging the GitHub OAuth integration, also ensuring that the implemented helpers/functions/api in this iteration resemble the ones that was made available by the GitHub App to reduces the amount of changes I was going to make across the entire codebase in acknowledgement of the new implementation.

The Trade Offs

GitHub App is great, I must acknowledge that I still have it in my mind for the future if we end-up finding a solution to the Error: Resource not accessible by integration error, but the functionality to create a Pull Request performed by the submit-word script is an imperative part of the project, so you bet we gotta make sure it works.

It's important to state that there was some trade-offs that I had to settle for in favor of the functionality...

No More Short-live token - the GitHub App provides an accessToken that expires after a certain period and a refreshToken to refresh this token; this is very good for security; Unlike OAuth App that provides an accessToken that never expires at all, and doesn't provide a refreshToken ofcourse
No More token that works only through jargons.dev - I understood (important to state) that accessToken generated via OAuth flow initiated through jargons.dev can only be used to make request through jargons.dev, making it not-possible to take this token to use as authorization elsewhere; Unlike OAuth App that provides accessToken that can be grabbed and used any where else like you would use a normal personal access token generated from your GitHub accounts.

The Workarounds

No More Short-live tokens - I intentionally added an 8 hours expiry for the accessToken when saving it to cookie to ensure that it atleast gets deleted from cookie, hence triggering a new OAuth flow to ensure a new accessToken (if that truly is the case) is generated from the flow.
No More token that works only through jargons.dev - Haha, it is imperative to state that at the point when we save the accessToken to cookie, it get encrypted, which means it is less-likely that the encrypted token is useful anywhere else because they'd need to decrypt something that we have encrypted. So you can say we have placed a lock on the token that only jargons.dev can unlock.

See PR:

refactor(auth): replace `github-app-oauth` with classic `oauth` app #33

babblebey posted on Apr 07, 2024

This Pull request refactors the authentication system, replacing the usage of github-app-oauth with classic github oauth app. This decision was taken because of the limitations discovered using the Pull Request endpoint (implementation in #25); the github-app-oauth uses permissions which requires a user to have write access to the upstream (i.e. write access to atleast pull-requests on our/this project repo) before a pull request can created from their forked repo branch to the main project repo.

This PR goes to implement classis oauth app, which uses scopes and allows user access to create the pull request to upstream repo on the public_repo scope. The changes made in this PR was done to mimic the normal Octokit.App's methods/apis as close as possible to allow compatibility with the implementation in #8 and #28 (or for cases when we revert back to using the github-app-oauth in the future --- maybe we end up finding a solution because honestly I really prefer the github-app-oauth 😉).

It is also important to state that this oauth app option doesn't offer a short lived token (hence we only have an accessToken without expiry and No refreshToken), but I have configured the token to expire out of cookie in 8hours; even though we might be getting exactly thesame token back from github after this expires and we re-authorize the flow, I just kinda like that feeling of the cookies expiring after some hours and asking user to re-auth.

Changes Made

Initialized a new app object that returns few methods and objects

octokit - the main octokit instance of the oauth app

/**
 * OAuth App's Octokit instance
 */
const octokit = new Octokit({
  authStrategy: createOAuthAppAuth,
  auth: {
    clientId: import.meta.env.GITHUB_OAUTH_APP_CLIENT_ID,
    clientSecret: import.meta.env.GITHUB_OAUTH_APP_CLIENT_SECRET
  },
});

oauth

getWebFlowAuthorizationUrl - method that generates the oauth flow url

/**
 * Generate a Web Flow/OAuth authorization url to start an OAuth flow
 * @param {import("@octokit/oauth-authorization-url").OAuthAppOptions} options
 * @returns 
 */
function getWebFlowAuthorizationUrl({state, scopes = ["public_repo"], ...options }) {
  return oauthAuthorizationUrl({
    clientId: import.meta.env.GITHUB_OAUTH_APP_CLIENT_ID,
    state,
    scopes,
    ...options
  });
}

exchangeWebFlowCode - method that exchanges oauth web flow returned code for accessToken; this functionality was extracted from the github/oauth/authorize endpoint to have all auth related function packed in one place

/**
 * Exchange Web Flow Authorization `code` for an `access_token` 
 * @param {string} code 
 * @returns {Promise<{access_token: string, scope: string, token_type: string}>}
 */
async function exchangeWebFlowCode(code) {
  const queryParams = new URLSearchParams();
  queryParams.append("code", code);
  queryParams.append("client_id", import.meta.env.GITHUB_OAUTH_APP_CLIENT_ID);
  queryParams.append("client_secret", import.meta.env.GITHUB_OAUTH_APP_CLIENT_SECRET);

  const response = await fetch("https://github.com/login/oauth/access_token", {
      method: "POST",
      body: queryParams
    });
  const responseText = await response.text();
  const responseData = new URLSearchParams(responseText);

  return responseData;
}

getUserOctokit - method that gets an octokit instance of a user.

/**
 * Get a User's Octokit instance
 * @param {Omit<OctokitOptions, "auth"> & { token: string }} options
 * @returns {Octokit}
 */
function getUserOctokit({ token, ...options }) {
  return new Octokit({
    auth: token,
    ...options
  });
};

Integrated the app.oauth.exchangeWebFlowCode method into the github/oauth/authorize endpoint handler
Removed the refreshToken and refreshTokenExpiresIn from github/oauth/authorize endpoint response object.
Modified doAuth actions
- Removed jargons.dev:refresh_token value set to cookie;
- Corrected computation of userOctokit to use app.getUserOctokit from app.oauth.getUserOctokit (even though I could just move the getUserOctokit method to the app.oauth object in the new implmentation, I just prefer it this way 😉).

📖

Screencast

screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.04.07-07_37_31.webm

View on GitHub

Building jargons.dev [#3]: The Word Editor

Olabode Lawal-Shittabey — Thu, 22 Aug 2024 16:26:11 +0000

In no time, we're here!

The editor is surely a part of the important piece of this project, the part that facilitates user's contribution; the dreamy 😊 interface where a user's can basically write/edit jargons and submit with the click of a button and boom that's a contribution to Open source that also gets a green square without interfacing with the GitHub UI or any code editor.

The Plan

Right from the initial commit, I had found and readied a library that I wanted to integrate for this Editor feature, this was a project that I found during my search for a visual editor tool that builds down to markdown — I needed this tool at a certain point to write some issue with some complex table structure on the Hearts repo.

It is MDXEditor

MDXEditor; quoting from the project website..

is an open-source React component that allows users to author markdown documents naturally. Just like in Google docs or Notion.

...and I'll add that it's a beautiful tool in itself, with their live demo being of great use to me.

So, MDXEditor had the finest selling point and trust me I was just sold 🤤.

Change of Plan

Unfortunately at the point of integration, I encountered an error; a commonJS related error in lexical — a text editor framework integrated in MDXEditor itself. I did some findings and documented source of error in the tweet below..

// Detect dark theme var iframe = document.getElementById('tweet-1772939694029832414-497'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1772939694029832414&theme=dark" }

I tried a few workarounds to get it working; but in order for the workaround to work, the lexical's integration version in MDXEditor needs to be updated.

I also immediately sourced for alternatives, and I found some but I wasn't feeling them at all.

The Resolution

I ended resolving to make a custom minimal markdown editor

// Detect dark theme var iframe = document.getElementById('tweet-1772939881276203492-305'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1772939881276203492&theme=dark" }

...and for a resolution to the error I encountered in my attempt to integrate MDXEditor, we still gotta do this for Open Source.

// Detect dark theme var iframe = document.getElementById('tweet-1772946130784923929-450'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1772946130784923929&theme=dark" }

The Editor

I got working, with the goal of relying on little to no dependency to patch the feature; I ended up consuming just react-markdown as new dependency and I was able to conclude the very first iteration of the editor in a 6 stages step.

// Detect dark theme var iframe = document.getElementById('tweet-1773392644128813245-171'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1773392644128813245&theme=dark" }

The Stages

I added a new map type $dictionaryEditor state to the dictionary store and a custom useDictionaryEditor hook which wraps around the store so I can use it in the next stage.
I added a boilerplate word-editor island with react integration. Integrated the island to with client:load directive on a newly created editor page/route.
I Implemented the Editor component within the word-editor island with textarea form element. I integrated the useDictionaryEditor to set dictionary store value for editor.
I implemented the Preview component within the word-editor island. Where I consumed a react-markdown as markdown converter to HTML for the preview purpose.
I created and integrated a DummyPreviewNavbar component into the Previewcomponent to enable the preview tab of the editor look exactly like word looks like when seen in the word layout on the web app.
I implemented the editor title field; added a non-functional "Publish" button.

The PR

feat: implement dictionary word editor #6

babblebey posted on Mar 26, 2024

This Pull Request implements the first iteration of the visual word editor for adding new or modifying existing words in the dictionary.

Changes Made

Added a new page/route /editor
Added a word-editor island with react integration and integrated this island on the editor page with a client:load directive
Added a new map store $wordEditor to stores/dictionary
Implemented a custom hook useWordEditor which serves as a wrapper to perform get and set operation on the $wordEditor store
Implement 2 component to the word-editor island integrate within the main island default exported component
- Editor - the entry field component for editing word entry to the dictionary, it implements the title field of input type text and a content field of textarea which receives (Markdown) text content
- Preview - the preview UI that mimics the view of word as it's going to look on the dictionary live view;
  - this component also integrate another DummyPreviewNavbar component to enhance the live preview idea
  - it also implements the Markdown component from react-markdown node module integration to parse of the Markdown content received from the Editor's content to html.
  - this component also uses the prose utility class name from @tailwind/typography plug-in to style the parsed html content enhance the preview idea.
Implemented the DummyPreviewNavbar component in within the word-editor island for integration in the Preview component
Implement a stateless/non-functional Publish button on editor page
Extracted nav element on layout/base to standalone Navbar component

📖

Screencast/Screenshot

screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.03.28-16_14_26.webm

Note

Added new node module: react-markdown

View on GitHub

Building jargons.dev [#2]: The Dictionary Search Engine

Olabode Lawal-Shittabey — Mon, 19 Aug 2024 13:18:25 +0000

What is a Dictionary without a search engine or ummm the search feature!?

During the implementation of the base dictionary, I had created these static Search forms (one on the homepage and the other on the Navbar used on the word layout) in preparation for this particular feature.

I just needed to pick-up from right there and get it working, easy work — if only that was true.

Something from the past

It is important to re-iterate that my initial plan was to build jargons.dev with Nextra as I admitted in the initial commit that:

...Nextra (this was infact my knight in shiny armor, I was looking to build with Nextra).

I am a React ⚛️ fan boy, big on Next.js; Nextra is a content-focus web framework that is built on Next.js. So I guess you can just understand why Nextra sounded like a that knight. During my initial exploration of Nextra, one feature stood out to me; the full-text search — I drooled 🤤over this one (I must confess).

The feature was powered by flexsearch — a zero-deps full-text search library; ooh boy I'm a big fan of lightweight and no/low dependencies. I dug into how Nextra uses this to index content at build-time for search; it was interesting.

So!?

I found myself hacking with flexsearch during my early encounter with Astro; as I followed the astro doc's build a blog tutorial, I went a notch further to implement a search feature very easily.

So, the experience from this implementation; I passed down to the search engine for jargons.dev.

The Search Engine

The task was pretty simple, I needed to..

Get access or call it reference to all files inside of the dictionary directory of words - at this point it was the src/pages/word directory
Get these files content indexed with flexsearch
Plug in the search form and boom 😉

Looks very easy! Maybe for the search indexing and actual searching, it was; but there was some lot of stuffs that went into getting there.

Integrating the first "Island" in jargons.dev

Astro by default takes a server-first approach, meaning it builds your site's HTML/CSS on server removing all client-side javascript (JS) automatically (unless you state other wise). Removing all JS assures performance improvement, but No JS means no interactivity; But if you want interactivity, Astro Island is one of the ways to go. I need the interactivity for the Search Engine so Island it is!

What's an "Island" though!?

I will put simply that an Island is an isolated interactive piece of component on a web page, whose HTML/CSS are rendered on the server-side and/but it's client-side javaScript are (hydrated) also bundled with it - NOT removed.

I gave a talk about Island at TILConf'24, Check it out to learn more.

Astro's offering

Astro offered support for integrating Islands out the box with my favorite UI library (yea, you guessed it, React) of many others. This allowed me build my static Search forms into a functional stuff.

Stuffs I did

I started by adding the integration module (@astrojs/react) for the Island I needed to integrate; done pretty easily with the npx astro add react command
I transferred all the static search forms into single React component (these are two differently sized forms); configured the component to render these at required size based on given props.
I also implemented some sub-component within that are only consumed locally in the-same search component, these are...
- The SearchDialog - main component where the search operation is carried out
- The SearchResult component, etc...
I implemented some custom keyboard shortcuts and keybinds that enables interactions with the search component (I'd like to call this "Search Island" from now on), these are...
- CTRL+K or ⌘K to start search
- ESC to close search
- ...and base required navigation buttons to navigate within search results
I also added a few custom hooks to allow smooth sailing in the working of the search island, these are...
- useLockBody - a hook that disables scrolling once the search dialog is opened
- useRouter - a hook that I made as wrapper around some window.location methods, making them to feel like the known router libs in React, this is a hook I particularly consumed on the ENTER button click handler in the navigation button keybind on search results component in the search island.
- and useIsMacOS - which checks whether a machine is MacOS in order to determine the appropriate description text to render on the search form trigger; i.e. CTRL+K or ⌘K
I added the imperative module - flexsearch;
I retrieved access to files the directory of words using the Astro.glob() function super easily (too bad I couldn't talk about how powerful this function is; how glad I am it existed out-the-box in Astro and how much ease it brought into the flow of getting this search engine up and running) and plugged the returned array of word objects into a $dictionary state (maybe I should call this a store) powered by nanostore (another beautiful stuff right there)
This $dictionary are then indexed with flexsearch, prepping them for later search.

Another Imperative feature: The Recent Searches

This is another imperative feature that I must talk about; This feature keeps track of searched items and stores them in localstorage to persist them on page reload; these store searched items are then render in a list on the homepage of the dictionary.

It also took integration as an Island, couple with a holding the value in a nanostore powered $recentSearches state.

My implementation of this feature isn't exactly perfect, and here are a list of some Issues that needed fix (at time of writing) to take it a step further down that route (even though we can never reach perfection, YEA for sure)

Add Loading Component to Recent Searches Island - https://github.com/devjargons/jargons.dev/issues/31
Bug: Search Operation Performed with Search Form in Navbar Overwrites LocalStorage - https://github.com/devjargons/jargons.dev/issues/10
Enhancement: Word Editor - Second Iteration Features - https://github.com/devjargons/jargons.dev/issues/9

The PR

This is some long read now, I wish to keep this reads short... Here's the PR

feat: implement dictionary search engine #5

babblebey posted on Mar 25, 2024

This Pull Request implement the search functionality to the dictionary project. It uses @astro/react integration to power the Islands coupled with nanostore for state-management and flexsearch as text search library.

Changes Made

Added the following astrojs integration and lib required to text search
- @astrojs/react
- @nanostores/react
- flexsearch
Implemented the Search Island (a react component) within where other sub components are implemented for internal usage
- Implemented the SearchTrigger component which render a search field of two different sizes and used in two different places on the web page...
  - size md - used on the main page of the web app
  - size sm - used on the dictionary word layout navigation section
- Implemented the SearchDialog component, which renders only when the SearchTrigger is clicked
- Implemented the SearchInfo component, renders as default placeholder when no search term has been inputted in form field
- Implemented the SearchResult component, renders either search results or a message for a search results not found
- Implemented keybinds within Search island to allow the following operation with the stated keyboard shortcuts
  - CTRL+K or ⌘K to open the search dialog without clicking on the search tigger
  - ArrowUp, ArrowDown and Enter to allow navigation on the Search results list
  - ESC to allow closure of search dialog
- Added the custom hooks for consumption on the Search island
  - useIsMacOS - check whether current user is browsing the web app with a MacOS machine; this is used to determine the appropriate short to render on the search trigger; i.e. CTRL+K or ⌘K
  - useLockBody - used to disable current viewport from scrolling when search dialog is opened
  - useRouter - (instead of adding react-router to deps) this hook wraps around window.location and uses the assign object as push; mainly used in the SearchResult component to route to selected/clicked result page
- Implemented searchIndexing on Search island with flexsearch's Document method as preferred option
  - Added a new search store for managing the search-related states with nanostores and @nanostores/react integration
  - Added the following store values and actions
    - $isSearchOpen - global state for managing the state of SearchDialog
    - $recentSearches - state for keeping track of recently searched words; it works in collab with the localStorage to persist its value even after tab reloads
    - $addToRecentSearchesFn - a store action that adds new item to $recentSearches store value
Added a $dictionary store for managing the entire dictionary entries; keeping it accesible to the client and used as value for searchIndex in the Search island
- Computed value for the dictionary store as early as possible from the layout/base with the Astro.glob() method indexing the entire dictionary directory
Added the RecentSearches island which reads the value from the $recentSearches store and renders it on the homepage

Screencast

Full Demo

screencast-bpconcjcammlapcogcnnelfmaeghhagj-2024.03.25-13_32_30.webm

📖

View on GitHub

Building jargons.dev [#1]: The Base Dictionary

Olabode Lawal-Shittabey — Tue, 13 Aug 2024 14:53:39 +0000

Welcome to the second installment of our series on jargons.dev!

Let's get to it!

Following the initial commit, I started working on "the fork script" (wondering what that is?? You'll find out later in the series 😉) but I must confess and as you'll find in the commit history, that I took a long break (3 months+) from working on jargons.dev. Within these times I've had some opportunity to do some subconscious reflection that was great for the project.

Reflection Opportunity

I stopped work on jargons.dev for the while, not intentionally but because I was so embedded in the work I was doing on Hearts, that I didn't even think about jargons.dev. Well, over the course of those months, the new year came (with new goals of-course), I've also experienced and gotten exposed to some new technologies. One technology stood out to me and that was Astro.

Astro Resonating with jargons.dev

In January, I had a goal of "learning new technologies with docs", this was a challenge that got me started with Astro after hearing great stuff about it.

// Detect dark theme var iframe = document.getElementById('tweet-1744263459867410930-653'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1744263459867410930&theme=dark" }

Fast forward March, I found myself working on another entirely different side project (wp-theme), I was watching a Eddie Jaoude YT Stream where I made this known to Eddie but his response would end up pushing me back to working on jargons.dev

// Detect dark theme var iframe = document.getElementById('tweet-1768395047462981963-11'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1768395047462981963&theme=dark" }

You have quite a few side projects... I don't know which one.

This statement got me to think real hard, hence I decided to halt all the lots of side projects and focus on some that mattered right away, jargons.dev easily came back to mind.

At this point, I was already somewhat familiar with Astro, — being a framework for content-driven web apps, with a super simple file system, i18n-ready, SSG with great SEO (important for the project), performant, support for other frontend libraries like ReactJS with islands (I love this one especially); it was a tool made in heaven to build jargons.dev with.

Well, I quickly got to work the next available weekend I had to work on the base dictionary part of the project.

// Detect dark theme var iframe = document.getElementById('tweet-1771908483828363760-160'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1771908483828363760&theme=dark" }

The Base Dictionary

I initialized a new Astro project for this one, as simple as running the command below and follow the prompts...

npm create astro@latest

I also added the tailwindcss integration for styling; mdx integration for content; this was also super easy to config by just running the command respectively

npx astro add tailwind
npx astro add mdx

I went on and completed the following tasks

Created a boilerplate homepage with static search form
Temporarily resolved to have the src/pages/word directory as the directory that should hold each word in the dictionary as a mdx file.
Implemented the word.astro layout, which serves as the frame within where all .mdx files' content for words inside of the src/pages/word/ directory can be rendered using frontmatter.
Also added a static mini search form to the word layout navbar.

With this feature, we are already able to view dictionary word on the jargons.dev/word/[word]route. This means when the file tuple.mdx is present in the src/pages/word/directory, we will be able to reach the page to get see the dictionary word with a visit to jargons.dev/word/tuple

The PR

feat: implement base dictionary #4

babblebey posted on Mar 24, 2024

This Pull request implements the base dictionary app with AstroJS

Changes Made

Started new astro project
Created homepage
Implemented 2 layouts
- Base - main primary wrapper for all pages and layouts
- Word - layout to be used on the word pages
Implemented static search form triggers on homepage and in Word layout

Screenshots

Homepage

Word page

View on GitHub

Building jargons.dev [#0]: The Initial Commit

Olabode Lawal-Shittabey — Mon, 12 Aug 2024 13:46:56 +0000

Yo, my first blog post! I don't even know how to start this haha, but I will just get started 🫣.

Intro

This is the "init" part of a blog series documenting my journey behind building jargons.dev. When I first ideated jargons.dev, I wanted to build it openly, sharing every step with the community. But I was also working on another project called "Hearts ❤️" which required my full attention. To manage both effectively, I decided to work on jargons.dev in a private repository.

Even though it wasn't built entirely in public, I've sort'a documented my thought process and decisions behind imperative pull requests. This series will take you behind the scenes, sharing the challenges, solutions, and lessons learned along the way.

Bits about me 🤭 (or skip to save the read)

My name is Olabode, nothing much to know about me other than I've been in tech for quite a while but not exactly very seriously IMO until I decided and took the biggest decision in my life by quitting my (6-figure paying) 9-5 back in September 2021 to focus on tech (now I wanna be serious 😤). This happened after some thought of how I started, got to where I was at and where I just wanna be (a story for another blogpost for sure). Fast forward June 2023, after the learnings, struggles and all, I discovered "Open Source" which became a thing for me since then to the point it earned me an opportunity to work on the project called "Hearts ❤️ (a recognition tool for open source)" where I have just gathered some how-it-should-be-done product building experience. Prior to this (in my past) I had always built stuffs differently, (yea, a not-so-good kind of different 😂); So with my experience working on "Hearts ❤️", I set out to build something (not just anything) in the how-it-should-be-done way ☝🏾.

About jargons.dev

// Detect dark theme var iframe = document.getElementById('tweet-1816783659325661250-279'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1816783659325661250&theme=dark" }

See, I'm an idealistic (that wasn't supposed to sound bad 🫣) person, I just get the weirdest ideas, which typically comes from a place of needing to scratch an itch and I surely do well to write these ideas down.

So jargons.dev (aka DevJargons) is an idea that came from the perspective of a dude called "Ola" (I can't promise you that's not me 😉); Ola is a super dumb learner who's mostly caught-up in a Technical Jargons hell; when Ola tries to learn/get definition to a technical term, he gets met by another term within, that requires definition and another and another. It's also not very easy to google search this terms especially because some of these terms likely shares context with fields/industries other than tech or software engineering. jargons.dev was just going to scratch this itch by being that one-stop dictionary that offers clear, easy-to-understand definitions to these terms.

The Initial Commit

Hold-up, we cannot go further without talking about "the notepad"

The Notepad

What about this!? Yea, this is one of my oldest Notepad where I write these weird ideas. Sometime in november 2023, I wrote the tweet below, it was "the Notepad" posing with a work laptop (a Microsoft Surface Laptop 2) I had just got as tiny upgrade from my 6years old Lenovo IdeaPad 100.

// Detect dark theme var iframe = document.getElementById('tweet-1724832031345889535-897'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1724832031345889535&theme=dark" }

So yea, this Laptop was super fast and I was pumped, I just wanna build stuffs. Hence, I picked the smallest and easiest to work on idea from the notepad; that was jargons.dev. I started cooking right away and its imperative to state that I started to do it in the how-it-should-be-done way.

// Detect dark theme var iframe = document.getElementById('tweet-1726259841256268036-466'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1726259841256268036&theme=dark" }

Approaching the initial commit

I stated that it was important for me to do this in the how-it-should-be-done way, so I leveraged my experience working on hearts by starting with developing a system architecture and a concept note for how the project would work.

Concept Note and System Architecture: https://persistent-lan-c5e.notion.site/dictionry-a12ac63f23a645a9b2275d829adbae25

At this point for jargons.dev, I had muted that it will be an Open Source dictionary that can accept word contribution, it will not require a server, it will rely on GitHub as backend, using a bunch of md files similar to The Odin Project and doc sites implemented like Nextra (this was infact my knight in shiny armor, I was looking to build jargons.dev with Nextra) but I also want to make contributing to the dictionary fun, and lovable with a streamlined contribution experience.

Having worked (for 2 months already) on "Hearts" at that point where I've consumed the GitHub APIs heavily, I found that I could leverage some GitHub endpoints to create a "wiki"-like experience 🤔 by providing a UI where contributors can add new or edit existing word on the dictionary which ends up as a Pull request — a contribution to Open Source, without interfacing with the GitHub UI or any IDE for word contribution.

The Commit

Now I understood the assignment and I got to work, I initialized the repository under the initial name "dictionry", a name that was initially a typo but stuck with me...

https://github.com/jargonsdev/jargons.dev/commit/8dc21f0fb6036563f826199ea39490bf77c4b34d

...and I merged the first PR to add octokit as the first node module to the project...

feat: initialize dictionry #1

babblebey posted on Dec 17, 2023

PR adds octokit javascript SDK for consuming GitHub api

View on GitHub

This was the start of something fun 🤌🏾

DEV Community: Olabode Lawal-Shittabey

Continuous AI Maturity Model: Where Do You Stand in the CAI Adoption?

What is the Continuous AI Maturity Model?

Level 1 — Manual AI assistance

Examples of level 1

Level 2 — Workflow automation

Examples of level 2

Level 3 — Zero intervention workflows

Examples of level 3

Why it matters

Moving up the levels

Reflection

Why Continuous AI Matters for Developers and Teams

Gains For Indie Developers: Becoming Amplified

Gains For Teams: Shared Intelligence at Scale

The Real Gain: Flow

Getting Started with Continuous AI

Continuous AI: A Simple Introduction

What is Continuous AI?

Examples of Continuous AI in Action

Here so...

How to Get Started with Continuous AI Tools

Building jargons.dev [#7]: The Word Editor Script

The Functional Breakdown

The PR

Changes Made

Screencast/Screenshot

Building jargons.dev [#6]: The Branch Script

The Script

The PR

Changes Made

Screencast/Screenshot

Building jargons.dev [#5]: The Fork Script

What are these scripts?

A Truth worth stating

The Script

The Steps

My weird assumption

The PR

Changes Made

Related Issue

Screencast/Screenshot

Changes Made

Building jargons.dev [#4]: The Authentication System

The Iterations

First Iteration

Changes Made

Integration Demo: Protect /sandbox page

Screencast/Screenshot

Note

Second Iteration

Changes Made

Related Isssue

Third Iteration

The Limitation

The Swap for GitHub's OAuth App from GitHub App

The Trade Offs

Changes Made

Screencast

Building jargons.dev [#3]: The Word Editor

The Plan

It is MDXEditor

Change of Plan

The Resolution

The Editor

The Stages

The PR

Changes Made

Screencast/Screenshot

Note

Building jargons.dev [#2]: The Dictionary Search Engine

Something from the past

So!?

The Search Engine

Integrating the first "Island" in jargons.dev

What's an "Island" though!?

Astro's offering

Stuffs I did

Another Imperative feature: The Recent Searches

The PR

Integration Demo: Protect `/sandbox` page